@fluentui/react-tabs 1.0.0-beta.99 → 9.0.0-beta.12

package/README.md

@@ -2,21 +2,4 @@
 
 **React Tabs components for [Fluent UI React](https://developer.microsoft.com/en-us/fluentui)**
 
-The `Tabs` control (formerly `Pivot`) is used for navigating frequently accessed, distinct content categories. Tabs allow for navigation between two or more content views and relies on text headers to articulate the different sections of content.
-
 These are not production-ready components and **should never be used in product**. This space is useful for testing new components whose APIs might change before final release.
-
-To import React Tabs components:
-
-```jsx
-import { Tabs, TabItem } from '@fluentui/react-tabs';
-
-const App = () => {
-  return (
-    <Tabs>
-      <TabItem headerText="Hello">Hello</TabItem>
-      <TabItem headerText="World">World</TabItem>
-    </Tabs>
-  );
-};
-```

package/Spec.md

@@ -0,0 +1,433 @@
+# @fluentui/react-tabs Spec
+
+# Tabs
+
+**GitHub Epic issue** - [Tabs/Pivot Convergence #20338](https://github.com/microsoft/fluentui/issues/20338)
+**Figma** - [Tabs](https://www.figma.com/file/dK5AnDvvnSTWV9lduQWeDk/Tabs)
+
+## Background
+
+Tabs allow for navigation between two or more content views and relies on text headers to
+articulate the different sections of content.
+
+There are a few different components typically provided for tabs:
+
+- Tab or tab header. This is the individual tab the user clicks to display content. It most often has text, an icon, or both.
+- Tab list or tab strip. This is a container for tabs and provides single selection behavior.
+- Tab panel. This is a container for the content to display when an associated tab is selected.
+
+In some cases the tab list and tab panels are provided together in a "tabs" aggregate component. This is historically done to provide the manilla folder tab style where the tab list and tab panels are arranged next to each other.
+
+## Prior Art - Open UI
+
+Naming: The Open UI component naming matrix indicates Tabs is the most common and popular name for this component.
+Only Fabric/Fluent UI v8 and earlier named it Pivot.
+
+The [Tabs Research](https://open-ui.org/components/tabs.research) notes part naming and terminology are not
+very consistent across libraries.
+
+The API and implementations depend on how tabs are conceptualized and integrated with existing components.
+For example, a set of tabs can be thought of as:
+
+- a set styled buttons with radio selection behavior
+- a menu list of menu items that toggle
+- a command bar with radio buttons plus other commands and components
+- a stack of components expected to render their state based on single/multi-select data.
+
+Features common to most libraries:
+
+- Grouping and consistent appearance across tabs within the same tab list
+- Focus trap and keyboard commands for switching tabs
+  - Left/Right and Up/Down arrow keys when focus trapped
+  - Ctrl+Tab/Ctrl+Shift+Tab for cycling next/previous
+- Text, an icon, or text with icon for tab content
+- Horizontal or vertical layout
+- LTR and RTL layout (i.e. ordering of tabs)
+- Overflow or scrolling when tabs do not fit within available space
+
+Features common to some libraries:
+
+- Keyboard commands for individual tab focus navigation
+  - Tab/Shift+Tab to cycle focus through tabs
+  - Space bar to select currently focused tab
+- Tab list containing both tabs and tab panels.
+- Conditionally render or show/hide of tab panels based on current tab selection.
+
+Advanced features supported by only a few libraries:
+
+- Close/Hide individual tabs
+- Tabs with drop-down content menus
+- Reordering tabs, sometimes with drag-and-drop
+- State indicators via badges
+- Show or scroll to a specific tab (i.e. ensure visible and selected)
+
+Given the ARIA standard roles of tablist and tab we can follow with TabList and Tab components.
+
+## Prior Art - Comparison with v0 and v8
+
+The existing components are:
+
+- v0 - [Menu](https://fluentsite.z22.web.core.windows.net/0.59.0/components/menu/definition)
+- v8 - [Pivot](https://developer.microsoft.com/en-us/fluentui#/controls/web/pivot)
+
+### Approach
+
+v0 Menu provides tabs, toolbars, menus, and breadcrumbs.
+v0 Menu supports tabs interaction when accessibility={tabListBehavior}
+
+v8 provides a separate Pivot component with tabs behavior and appearance customization.
+
+### Appearances
+
+#### **Pivot**
+
+A 'Pivot' appears as a horizontal set of borderless buttons with an underline indicating current selection.
+
+v0 and v8 provide a 'Pivot' appearance.
+v0: underlined=true
+v8: by default
+
+#### **Block Tab**
+
+A 'Block Tab' appears as a horizontal set of borderless buttons.
+The selection has an active color, rectangular background.
+
+Both v0 and v8 provide the 'Block Tab' appearance.
+v0: by default
+v8: linkFormat="tabs"
+
+#### **Variations**
+
+v0 supports decorating tabs with arrows pointing toward the associated content.
+v0: pointing=true
+
+v8 supports a large tab style with increased padding per tab.
+v8: linkSize="large"
+
+### Tab Item Content
+
+Both v0 and v8 support text, icon, and text and icon as tab content.
+v0 additionally supports menus as tab content.
+
+Both v0 and v8 support custom rendering of tab content through a render props per item.
+
+### Tab Panel
+
+v0 does not provide a tab panel since it is implemented through the menu component.
+v8 supports the tab panel as the children of PivotItem. The tab content is provided through the header property.
+
+## Sample Code
+
+### Default
+
+By default tabs are arranged horizontally.
+Content within the tab is arranged horizontally.
+It is centered (horizontally and vertically).
+The default appearance is transparent.
+
+```tsx
+<TabList>
+  <Tab value="tab1">One</Tab>
+  <Tab value="tab2">Two</Tab>
+  <Tab value="tab3">Three</Tab>
+</TabList>
+```
+
+### Vertical
+
+The vertical prop causes the tabs to be arranged vertically.
+Content within the tab is still arranged horizontally and centered.
+
+```tsx
+<TabList vertical>
+  <Tab value="tab1">One</Tab>
+  <Tab value="tab2">Two</Tab>
+  <Tab value="tab3">Three</Tab>
+</TabList>
+```
+
+### Vertical Tab content
+
+The verticalTabContent prop causes the content within the tab to be arranged vertically.
+The content is still centered.
+If the icon prop is set, the rendered icon is part of the vertical tab content.
+
+```tsx
+<TabList verticalTabContent>
+  <Tab value="tab1">One</Tab>
+  <Tab value="tab2">Two</Tab>
+  <Tab value="tab3">Three</Tab>
+</TabList>
+
+<TabList vertical verticalTabContent>
+  <Tab value="tab1">One</Tab>
+  <Tab value="tab2">Two</Tab>
+  <Tab value="tab3">Three</Tab>
+</TabList>
+```
+
+### Appearance
+
+The default appearance is transparent.
+Transparent has no border and background styles.
+The selection indicator is a brand color line below the tab.
+Hovering over a tab shows a gray line below the tab.
+
+```tsx
+<TabList>
+  {/* ... */}
+</TabList>
+
+<TabList appearance="transparent">
+  {/* ... */}
+</TabList>
+```
+
+The subtle appearance is similar to transparent, but a light background is displayed when hovering over a tab.
+
+```tsx
+<TabList appearance="subtle">{/* ... */}</TabList>
+```
+
+### Size
+
+Small and medium sizes are supported.
+The size affects the padding and spacing between elements.
+Size can also affect the default icon (and badge) size.
+The default size is medium.
+
+```tsx
+<TabList size="small">
+  {/* ... */}
+</TabList>
+
+<TabList size="medium">
+  {/* ... */}
+</TabList>
+```
+
+### With Icon
+
+When the icon slot is filled, an icon is positioned before the tab content.
+
+```tsx
+<TabList>
+  <Tab icon={<CheckboxComposite />} value="allowed">
+    Allowed
+  </Tab>
+  <Tab icon={<BlockedSite />} value="blocked">
+    Blocked
+  </Tab>
+</TabList>
+```
+
+An icon only tab is displayed when the icon slot is filled and tab content is omitted.
+
+```tsx
+<TabList>
+  <Tab icon={<CheckboxComposite />} value="allowed" />
+  <Tab icon={<BlockedSite />} value="blocked" />
+</TabList>
+```
+
+## API
+
+### Tab
+
+TabCommons.value supports an arbitrary identifier value.
+This is similar to Accordion's selection approach.
+
+```ts
+export type TabValue = unknown;
+
+export type TabCommons = {
+  disabled?: boolean;
+  disabledFocusable?: boolean;
+  value: TabValue;
+};
+```
+
+Each tab has an icon slot.
+
+```ts
+export type TabSlots = {
+  root: IntrinsicSlotProps<'div'>;
+  icon?: IntrinsicSlotProps<'span'>;
+};
+```
+
+```ts
+export type TabProps = ComponentProps<TabSlots> & TabCommons;
+```
+
+### TabList
+
+The tab list only has the root slot.
+
+```ts
+export type TabListSlots = {
+  root: IntrinsicSlotProps<'div'>;
+};
+```
+
+The tab list supports tab selection events that include the value of the tab selected.
+
+```ts
+export type TabSelectedEvent<E = HTMLElement> = React.MouseEvent<E> | React.KeyboardEvent<E>;
+
+export type TabSelectedData = {
+  value: TabValue;
+};
+
+export type TabSelectedEventHandler = (event: TabSelectedEvent, data: TabSelectedData) => void;
+```
+
+Tab list supports default and selected values for controlled and uncontrolled scenarios.
+
+```ts
+export type TabListProps = ComponentProps<TabListSlots> & {
+  appearance?: 'transparent' | 'subtle';
+  defaultSelectedValue?: string | number;
+  selectedValue?: string | number;
+  size?: 'small' | 'medium';
+  vertical?: boolean;
+  verticalTabContent?: boolean;
+  onTabSelected?: TabSelectedEventHandler;
+};
+```
+
+The tab list communicates with tabs via context.
+This applies appearance, size, and layout.
+The tab can leverage the selectedValue and is expected to call selectTab when clicked.
+
+By adding these properties to TabProps we could allow individual tabs to override these values.
+However the expectation is that the tabs within a tab list have consistent layout and appearance.
+
+```ts
+export type TabListContextValue = TabListCommons & {
+  appearance: 'transparent' | 'subtle';
+  selectedValue: string;
+  size: 'small' | 'medium';
+  selectTab: SelectTabEventHandler;
+  vertical: boolean;
+};
+```
+
+## Structure
+
+- _**Public**_
+
+```tsx
+<TabList>
+  <Tab>One</Tab>
+  <Tab>Two</Tab>
+  <Tab>Three</Tab>
+</TabList>
+```
+
+- _**DOM**_
+
+```html
+<div role="tablist">
+  <div role="tab">One</div>
+  <div role="tab">Two</div>
+  <div role="tab">Three</div>
+</div>
+```
+
+## Migration
+
+### From v8
+
+1. Replace occurrences of `<Pivot>` with `<TabList>`
+2. Replace occurrences of `<PivotItem>` with `<Tab>`
+3. Replace `<PivotItem>` content with handling onTabSelected to show/hide associated content.
+4. Move PivotItem.headerText to be the content of Tab
+5. Subscribe to onTabSelected to show/hide content when a tab is selected.
+
+### From v0
+
+1. Replace use of `<Menu>` with `<TabList>`
+2. Replace items data with Tab instances, writing a `map` function as needed.
+
+## Behaviors
+
+### Selection
+
+TabList provides single selection of a tab.
+
+#### **Programmatic**
+
+The TabList.selectedKey can control the currently selected tab.
+The onTabSelected event informs callers of a selection change.
+The event data includes the tab value.
+
+#### **Mouse/Touch**
+
+Clicking the tab selects it.
+
+#### **Keyboard**
+
+The tab list will support the prescribed [ARIA keyboard interaction](https://www.w3.org/TR/wai-aria-practices-1.1/#keyboard-interaction-19).
+
+A Tablist allows focus of individual tabs.
+
+When the TabList has focus, the user can use arrow keys to move focus to the next or previous tab.
+The keys are based on layout. Horizontal uses left/right arrows and vertical uses up/down arrows.
+
+When the TabList has focus, the user can use the home/end keys to move focus to the first/last tab.
+
+A tab is selected when the spacebar/enter key is pressed for a focused tab.
+
+The `TAB` key moves focus out of the tabs.
+
+## Accessibility
+
+ARIA provides tab-specific roles:
+
+- [tab](https://www.w3.org/TR/wai-aria-1.1/#tab): A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.
+- [tablist](https://www.w3.org/TR/wai-aria-1.1/#tablist): A list of tab elements, which are references to tabpanel elements.
+- [tabpanel](https://www.w3.org/TR/wai-aria-1.1/#tabpanel): A container for the resources associated with a tab, where each tab is contained in a tablist.
+
+TabList and Tab will apply the `tablist` and `tab` ARIA roles.
+The `tabpanel` will be reserved for possible future component.
+
+### Screen readers
+
+Screen readers will read each tab's content.
+
+# Future
+
+## Overflow Button/Dropdown
+
+The design spec details a menu button (...) that displays the list of tabs that were not able to be displayed due to limited space. We have some concerns providing overflow as a default feature of tabs. The v1 of TabList and Tab will not include overflow.
+
+- Overflow made the v0 toolbar difficult to maintain. Customers hacked around it when it did not meet app requirements.
+- In v8, taking a dependency on menu over-complicated the button component and increased the default footprint. It also created a tighter binding with the overflow props matching the menu props and children.
+- Overflow dropdown is one of many possible approaches such as scrolling, paging, multi-row, scroll-into-view. This may be best left as an application-level concern.
+- The dropdown approach is called out by bootstrap as [problematic for usability and accessibility](https://react-bootstrap.github.io/components/tabs/#tabs-with-dropdown).
+- Many (if not most) component libraries do not support dropdown overflow.
+- There is not a general purpose overflow solution in vNext infrastructure. The team needs to explore options and formulate an approach.
+
+### Tab with Badge
+
+The design spec shows a badge which is arranged near the icon or text. The initial vNext package will not provide a badge variant or badge slot.
+
+- It is unclear if the badge is a common enough scenario to warrant the package dependency on react-badge.
+- The positioning of the badge relative to other parts is not confirmed in the design spec
+- Other controls may want to overlay a badge. We may want a general purpose badge overlay solution.
+- The badge appears most often in an app bar scenario. It is unclear if the items with badges are really tabs, or some other kind of command button. We may have a future app bar/nav bar/toolbar component that handles the badge scenario.
+
+> The intial work to explore supporting a badge used a BadgeTab variant.
+
+### TabPanel
+
+While the design spec does not cover tab panels, v8 Pivot supports them through the content of the PivotItem. They are also a common scenario when the tabs are adjacent to the content associated with each tab.
+
+- There are many approaches to handling tab panel content: show/hide, conditional render, navigation through a router
+- We're not providing a manilla folder tab appearance, so there is no need for the tab panel to support styling for when the components are co-located. We may want to have a manilla folder appearance.
+
+If/When we do support tab panels,
+
+- we should provide flexible composition. The tabs should be able to be placed independent of the tab panels in the DOM. The caller should be able to wire the two together easily through event callbacks or state binding.
+- we should make connecting tabs and tab panels easy by a Tabs container component that wires them together.

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+import type { ComponentProps } from '@fluentui/react-utilities';
+import type { ComponentState } from '@fluentui/react-utilities';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+import * as React_2 from 'react';
+import type { Slot } from '@fluentui/react-utilities';
+import { SlotClassNames } from '@fluentui/react-utilities';
+
+export declare type RegisterTabEventHandler = (data: TabRegisterData) => void;
+
+/**
+ * Render the final JSX of Tab
+ */
+export declare const renderTab_unstable: (state: TabState) => JSX.Element;
+
+/**
+ * Render the final JSX of TabList
+ */
+export declare const renderTabList_unstable: (state: TabListState, contextValues: TabListContextValues) => JSX.Element;
+
+export declare type SelectTabData = {
+    /**
+     * The value of the selected tab.
+     */
+    value: TabValue;
+};
+
+export declare type SelectTabEvent<E = HTMLElement> = React_2.MouseEvent<E> | React_2.KeyboardEvent<E>;
+
+export declare type SelectTabEventHandler = (event: SelectTabEvent, data: SelectTabData) => void;
+
+/**
+ * A tab provides a selectable item in a tab list.
+ */
+export declare const Tab: ForwardRefComponent<TabProps>;
+
+export declare const tabClassName: string;
+
+export declare const tabClassNames: SlotClassNames<TabSlots>;
+
+declare type TabCommons = {
+    /**
+     * A tab can be set to disable interaction.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The value that identifies this tab when selected.
+     */
+    value: TabValue;
+};
+
+/**
+ * A tab list provides single selection from a set of tabs.
+ */
+export declare const TabList: ForwardRefComponent<TabListProps>;
+
+export declare const tabListClassName: string;
+
+export declare const tabListClassNames: SlotClassNames<TabListSlots>;
+
+declare type TabListCommons = {
+    /**
+     * A tab list can supports 'transparent' and 'subtle' appearance.
+     *- 'subtle': Minimizes emphasis to blend into the background until hovered or focused.
+     *- 'transparent': No background and border styling
+     * The appearance affects each of the contained tabs.
+     * @default 'transparent'
+     */
+    appearance?: 'transparent' | 'subtle';
+    /**
+     * A tab list can be set to disable interaction.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Raised when a tab is selected.
+     */
+    onTabSelect?: SelectTabEventHandler;
+    /**
+     * The value of the currently selected tab.
+     */
+    selectedValue?: TabValue;
+    /**
+     * A tab list can be either 'small' or 'medium' size.
+     * The size affects each of the contained tabs.
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium';
+    /**
+     * A tab list can arrange its tabs vertically.
+     * @default false
+     */
+    vertical?: boolean;
+};
+
+export declare type TabListContextValue = Pick<TabListCommons, 'onTabSelect' | 'selectedValue'> & Required<Pick<TabListCommons, 'appearance' | 'disabled' | 'size' | 'vertical'>> & {
+    /** A callback to allow a tab to register itself with the tab list. */
+    onRegister: RegisterTabEventHandler;
+    /** A callback to allow a tab to unregister itself with the tab list. */
+    onUnregister: RegisterTabEventHandler;
+    /**
+     * A callback to allow a tab to select itself when pressed.
+     */
+    onSelect: SelectTabEventHandler;
+    /**
+     * Gets the registered tab data along with current and previous selected values.
+     */
+    getRegisteredTabs: () => {
+        selectedValue?: TabValue;
+        previousSelectedValue?: TabValue;
+        registeredTabs: Record<string, TabRegisterData>;
+    };
+};
+
+/**
+ * Context values used in rendering TabList.
+ */
+export declare type TabListContextValues = {
+    /**
+     * The context of the tab list available to each tab.
+     */
+    tabList: TabListContextValue;
+};
+
+/**
+ * TabList Props
+ */
+export declare type TabListProps = ComponentProps<TabListSlots> & TabListCommons & {
+    /**
+     * The value of the tab to be selected by default.
+     * Typically useful when the selectedValue is uncontrolled.
+     */
+    defaultSelectedValue?: TabValue;
+};
+
+export declare type TabListSlots = {
+    /**
+     * The slot associated with the root element of this tab list.
+     */
+    root: Slot<'div'>;
+};
+
+/**
+ * State used in rendering TabList.
+ */
+export declare type TabListState = ComponentState<Required<TabListSlots>> & TabListContextValue;
+
+/**
+ * Tab Props
+ */
+export declare type TabProps = ComponentProps<Partial<TabSlots>> & TabCommons;
+
+export declare type TabRegisterData = {
+    /**
+     * The value of the tab.
+     */
+    value: TabValue;
+    /**
+     * The reference to the tab HTML element.
+     */
+    ref: React_2.RefObject<HTMLElement>;
+};
+
+export declare type TabSlots = {
+    /**
+     * Root of the component.
+     */
+    root: Slot<'button'>;
+    /**
+     * Icon that renders before the content.
+     */
+    icon?: Slot<'span'>;
+    /**
+     * Component children are placed in this slot
+     * Avoid using the `children` property in this slot in favour of Component children whenever possible.
+     */
+    content: NonNullable<Slot<'span'>>;
+};
+
+/**
+ * State used in rendering Tab
+ */
+export declare type TabState = ComponentState<TabSlots> & Omit<TabCommons, 'disabled'> & Required<Pick<TabCommons, 'disabled'>> & {
+    /**
+     * A tab supports 'transparent' and 'subtle' appearance.
+     */
+    appearance?: 'transparent' | 'subtle';
+    /**
+     * A tab can have only an icon slot filled and no content.
+     */
+    iconOnly: boolean;
+    /**
+     * If this tab is selected
+     */
+    selected: boolean;
+    /**
+     * A tab can be either 'small' or 'medium' size.
+     */
+    size: 'small' | 'medium';
+    /**
+     * A tab can arrange its content based on if the tabs in the list are arranged vertically.
+     */
+    vertical: boolean;
+};
+
+/**
+ * Any value that identifies a specific tab.
+ */
+export declare type TabValue = unknown;
+
+/**
+ * Create the state required to render Tab.
+ *
+ * The returned state can be modified with hooks such as useTabStyles_unstable,
+ * before being passed to renderTab_unstable.
+ *
+ * @param props - props from this instance of Tab
+ * @param ref - reference to root HTMLElement of Tab
+ */
+export declare const useTab_unstable: (props: TabProps, ref: React_2.Ref<HTMLElement>) => TabState;
+
+/**
+ * Create the state required to render TabList.
+ *
+ * The returned state can be modified with hooks such as useTabListStyles_unstable,
+ * before being passed to renderTabList_unstable.
+ *
+ * @param props - props from this instance of TabList
+ * @param ref - reference to root HTMLElement of TabList
+ */
+export declare const useTabList_unstable: (props: TabListProps, ref: React_2.Ref<HTMLElement>) => TabListState;
+
+/**
+ * Apply styling to the TabList slots based on the state
+ */
+export declare const useTabListStyles_unstable: (state: TabListState) => TabListState;
+
+/**
+ * Apply styling to the Tab slots based on the state
+ */
+export declare const useTabStyles_unstable: (state: TabState) => TabState;
+
+export { }

package/lib/Tab.d.ts

@@ -0,0 +1 @@
+export * from './components/Tab/index';

package/lib/Tab.js

@@ -0,0 +1,2 @@
+export * from './components/Tab/index';
+//# sourceMappingURL=Tab.js.map

package/lib/Tab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tab.js","sourceRoot":"../src/","sources":["Tab.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC","sourcesContent":["export * from './components/Tab/index';\n"]}