DocumentTabs

Import

import { DocumentTabs } from '@envsemble/envui';

Usage

<DocumentTabs
  aria-label="Open documents"
  items={documents}
  value={active}
  onValueChange={setActive}
  onClose={close}
  panelId="document-panel"
/>
<div role="tabpanel" id="document-panel" aria-label={activeDocument.label}>…</div>

items are the open documents in tab order, each a DocumentTabsItem with its value, its label, an optional icon, a tooltip, the native tooltip, such as the full path, and preview. value is the active tab's value, or null. onClose is called from every way of closing a tab: remove the tab there, activate a neighbour when it was active, and ask first about unsaved changes.

Preview, pin and reorder

A preview tab's double click calls onPin, where the application clears preview. With onReorder, a drag or Move left and Move right report every tab's id in the new order; without it, the tabs keep their order.

Close all and after the tabs

Each tab opens a context menu with Close on right click, long press, the Menu key and Shift+F10. onCloseAll adds Close all tabs to it, and the strip around the tabs opens it too. end holds content after the tabs, outside the strip that scrolls, as the CloseAllButton example does.

Composition

closeLabel, a function of the tab's label, closeAllLabel and contextMenuLabel name the close actions and the menu. className, style, ref and the other native props reach the root, env-document-tabs, the bar that holds the strip and the end content. Each item, env-document-tabs-item, lays out its tab beside its close button, an IconButton with a cross hidden from assistive technology.

Accessibility

You provide

An aria-label for the strip, and the tabpanel with panelId, named after the active document.

envUI provides

A tablist of tabs with aria-selected, aria-controls and aria-keyshortcuts for the keys that close them.
Each close button beside its tab, hidden from assistive technology, so the context menu and the keys close it instead.
Touch-sized tabs, whose close buttons always show on coarse pointers.

Props

Editor-style closable tabs for open documents; the application renders the active document. className, style, ref and the other native props go to the root element, which holds the strip of tabs and the actions at its end.

Prop	Type	Description
`items`required	`readonly DocumentTabsItem[]`	The open documents, in tab order.
`value`required	`stringnull`	The active tab, or null.
`onValueChange`required	`(value: string) => void`	Called with the tab's value when it is clicked or reached with the arrow keys, Home or End.
`onClose`required	`(id: string) => void`	Called from a tab's close button, a middle click, Delete or Backspace on the focused tab, and Close in the tab's context menu.
`onPin`	`(id: string) => void`	Called when a tab is double-clicked, typically to keep a preview tab open.
`onReorder`	`(ids: string[]) => void`	Called with every tab's value in the new order when a tab is dragged to another place with a mouse or pen, or moved with Move left or Move right in its context menu, which also reach the keyboard and touch. Without it, the tabs keep their order.
`end`	`ReactNode`	Content after the tabs, outside the strip that scrolls and in line with it, such as a button that closes every tab or opens a new one.
`aria-label`required	`string`	Accessible name of the tab strip.
`panelId`	`string`	Id of the panel the application renders for the active tab.
`closeLabel`Default `'Close {label}', or EnvUIProvider's messages.documentTabs.close`	`(label: string) => string`	The name of the context menu's item that closes a tab, and the tooltip of its close button.
`onCloseAll`	`() => void`	Called from Close all tabs in the context menu. Each tab opens a context menu that closes it on right click, long press, the Menu key and Shift+F10; with onCloseAll, the menu also offers Close all tabs, and the strip around the tabs opens it too.
`closeAllLabel`Default `'Close all tabs', or EnvUIProvider's messages.documentTabs.closeAll`	`string`	Label of the Close all tabs item.
`contextMenuLabel`Default `'Tab actions', or EnvUIProvider's messages.documentTabs.contextMenu`	`string`	Accessible name of the context menu.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-document-tabs: The root: a bar that holds the strip of tabs and the content after it.
env-document-tabs-close: A tab's close button.
env-document-tabs-drag-image: The image that follows the pointer while a tab is dragged.
env-document-tabs-end: The actions at the end of the bar.
env-document-tabs-item: One tab with its close button.
env-document-tabs-list: The tabs of open documents, which scroll sideways.
env-document-tabs-tab: A tab's button.
env-document-tabs-tab-label: A tab's title.
data-active: Present on env-document-tabs-item
data-drop: after · before on env-document-tabs-item
data-fade-left: Present on env-document-tabs-list
data-fade-right: Present on env-document-tabs-list
data-moving: pointer on env-document-tabs-item
data-preview: Present on env-document-tabs-tab
data-reordering: Present on env-document-tabs-list
data-tab-id: Any value, or present on env-document-tabs-tab

Strings

EnvUIProvider's messages overrides each, and a component's own label prop wins over it.

messages.documentTabs.close: ({ label }) => string A tab's close button, such as Close Report.md.
messages.documentTabs.closeAll: "Close all tabs" Closes every tab.
messages.documentTabs.moveLeft: "Move left" Moves a tab one place to the left, in its context menu.
messages.documentTabs.moveRight: "Move right" Moves a tab one place to the right, in its context menu.
messages.documentTabs.contextMenu: "Tab actions" Names a tab's menu of actions.

Changelog

1.0.0: onReorder: a tab dragged with a mouse or pen shows where it will land and moves there when let go, and each tab's context menu offers Move left and Move right. end holds content after the tabs, such as a button that closes them all. Tabs that run past an edge fade out toward it. Rebuilt on Base UI Tabs: each tab sits beside its close button, an IconButton with a cross hidden from assistive technology, instead of around it, which fixes the nested-interactive control, and announces Delete and Backspace, which close it, through aria-keyshortcuts. Each tab opens a context menu with Close, also without onCloseAll, which adds Close all tabs. The arrow keys and the wheel follow the text direction. Strings come from messages.documentTabs, and the strip takes ref and style. Classes: env-document-tabs-item lays out each tab, and env-document-tab, -label and -close are env-document-tabs-tab, -tab-label and env-document-tabs-close. The root, env-document-tabs, is the bar that holds the strip and the end content, and takes className, style and ref; the strip, the tab list, which they reached before, is env-document-tabs-list.
1.0.0-prerelease.6: Colors under the pointer and while pressed change with --env-motion-ease-enter, rather than easing in slowly, so hover and press show from the first frame.

The active tab takes the surface of the content below it, which it joins, in place of the grey fill, which now marks hover alone.
1.0.0-prerelease.5: DocumentTab is DocumentTabsItem, keyed by value where it had id, with tooltip where it had title; the root takes the native props.