@adecore/ui 0.49.7 → 0.50.1

package/src/workspace/PaneBar.tsx

@@ -0,0 +1,276 @@
+import { useEffect, useRef, useState, type ComponentProps, type DragEvent, type ReactNode, type RefObject } from 'react';
+import { createPortal } from 'react-dom';
+import clsx from 'clsx';
+import { MoreHorizontal } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { CloseButton } from '../CloseButton.tsx';
+import * as ContextMenu from '../context-menu/index.parts.ts';
+import { IconButton } from '../IconButton.tsx';
+import * as Popover from '../popover/index.parts.ts';
+import { Separator } from '../Separator.tsx';
+import type { Shortcut } from '../shortcut.ts';
+
+/* What the bar holds that is not the bar: a press on one of these is not the start of a drag. */
+const CONTROLS = 'input, textarea, select, button, a, [contenteditable=""], [contenteditable="true"], [role="button"]';
+
+/* Without this margin, a bar right at the fold point would fold and unfold on every pixel of a splitter drag. */
+const UNFOLD_MARGIN = 24;
+
+/*
+ * Whether the actions are folded into the overflow menu: only once the title has shrunk to its glyph and
+ * the actions still do not fit. The width where that happened is remembered, since a folded bar fits by
+ * definition and can no longer tell by overflowing when there is room again.
+ */
+function useFolded(bar: RefObject<HTMLElement | null>, actions: RefObject<HTMLElement | null>, enabled: boolean): boolean {
+    const [foldedAt, setFoldedAt] = useState<number | null>(null);
+
+    useEffect(() => {
+        const element = bar.current;
+
+        if (!enabled || element === null || typeof ResizeObserver === 'undefined') {
+            return;
+        }
+
+        const measure = (): void => {
+            const width = element.clientWidth;
+
+            setFoldedAt((current) => {
+                if (current !== null) {
+                    return width > current + UNFOLD_MARGIN ? null : current;
+                }
+
+                return element.scrollWidth > width + 1 ? width : null;
+            });
+        };
+
+        const observer = new ResizeObserver(measure);
+
+        observer.observe(element);
+
+        // The actions change size on their own as well, as when a terminal's agent adds its mode.
+        if (actions.current) {
+            observer.observe(actions.current);
+        }
+
+        measure();
+
+        return () => observer.disconnect();
+        // Again on every fold: the actions are a new element each time they come back.
+    }, [bar, actions, enabled, foldedAt]);
+
+    // A pane that brings no actions has nothing to fold, whatever the bar measured before it changed.
+    return enabled && foldedAt !== null;
+}
+
+export interface PaneBarProps extends Omit<ComponentProps<'header'>, 'title' | 'children' | 'onDragStart' | 'onDragEnd'> {
+    /** What the pane is: a glyph and a name, or a `TabStrip` when `tabs` is set. */
+    title: ReactNode;
+
+    /** The title is a strip of tabs, which takes the bar's room and keeps the bar whatever tab is in front. */
+    tabs?: boolean;
+
+    /** The pane's own controls. They fold into a "More actions" popover once the title has given way and they still do not fit. */
+    actions?: ReactNode;
+
+    /** Keeps the actions in the bar of a pane with tabs, rather than in a bar of their own under it. */
+    compactActions?: boolean;
+
+    /** A separator between the title and the actions of a pane without tabs. */
+    separated?: boolean;
+
+    /** Between the title and the actions, such as a mark that lives on the line over the body. */
+    accessory?: ReactNode;
+
+    /** Before the close button, such as a sign that the pane fills the view. */
+    trailing?: ReactNode;
+
+    focused?: boolean;
+
+    onClose?(): void;
+    closeLabel?: string;
+    closeShortcut?: Shortcut | string;
+    moreActionsLabel?: string;
+
+    /** The items of the bar's context menu. Leave it out for a bar without one. */
+    menu?: ReactNode;
+
+    /** With `onDragStart`, the bar is a handle that drags the pane; a press on a control in it never starts one. */
+    onDragStart?(event: DragEvent<HTMLElement>): void;
+
+    onDragEnd?(event: DragEvent<HTMLElement>): void;
+
+    /**
+     * An element to draw the bar in instead of over the pane, such as the slot of a `WorkspaceTopRow`. The bar
+     * stays the pane's in the tree, so its events still reach the pane's handlers. A separator leads it there.
+     */
+    container?: HTMLElement | null;
+}
+
+/**
+ * The bar over a pane: its title or its tabs, its actions and its close button. Drawn in a `container` it
+ * takes that element's height and background, and only its title answers the pointer, so a window can be
+ * dragged by the rest.
+ */
+export function PaneBar({
+    title,
+    tabs = false,
+    actions,
+    compactActions = false,
+    separated = false,
+    accessory,
+    trailing,
+    focused = false,
+    onClose,
+    closeLabel,
+    closeShortcut,
+    moreActionsLabel,
+    menu,
+    onDragStart,
+    onDragEnd,
+    container = null,
+    className,
+    ...props
+}: PaneBarProps) {
+    const { t } = useTranslation('ui');
+    /* Whether the pointer came down on the bar itself. A drag starts on the nearest draggable ancestor, so
+       `draggable` on a child does not hold it back: the attribute itself has to go while the pointer is in a
+       control, or selecting text in an address field would drag the pane away instead. */
+    const [grabbable, setGrabbable] = useState(true);
+    const [menuOpen, setMenuOpen] = useState(false);
+    const bar = useRef<HTMLElement>(null);
+    const actionsBar = useRef<HTMLDivElement>(null);
+    const actionsRef = useRef<HTMLSpanElement>(null);
+    const hasActions = actions !== undefined && actions !== null && actions !== false;
+    const separate = tabs && !compactActions;
+    const folded = useFolded(separate ? actionsBar : bar, actionsRef, hasActions);
+    const inContainer = container !== null;
+    const draggable = onDragStart !== undefined;
+
+    const actionsPart = hasActions && (
+        <>
+            {!folded && (
+                <>
+                    {!tabs && separated && <Separator />}
+                    {/* The controls keep their minimum width so overflow can trigger folding. */}
+                    <span ref={actionsRef} className={clsx('flex min-w-min items-center', tabs && compactActions ? 'shrink-0' : 'grow')}>
+                        {actions}
+                    </span>
+                </>
+            )}
+            {folded && (
+                <Popover.Root open={menuOpen} onOpenChange={setMenuOpen}>
+                    <IconButton
+                        icon={MoreHorizontal}
+                        size="sm"
+                        label={moreActionsLabel ?? t('workspace.moreActions')}
+                        className="cursor-default"
+                        render={<Popover.Trigger />}
+                    />
+                    {/* A popover keeps the keys of controls such as an address field. */}
+                    <Popover.Popup sideOffset={6} align="end" className="flex min-w-72 items-center gap-2 p-2 text-xs">
+                        {actions}
+                    </Popover.Popup>
+                </Popover.Root>
+            )}
+            {/* Still mounted while folded, so what portals into the actions keeps its place to go. */}
+            {folded && !menuOpen && (
+                <span hidden className="hidden">
+                    {actions}
+                </span>
+            )}
+        </>
+    );
+
+    const header = (
+        <header
+            {...props}
+            ref={bar}
+            data-pane-bar=""
+            data-placement={inContainer ? 'container' : undefined}
+            draggable={draggable && grabbable}
+            className={clsx(
+                'ade-pane-bar flex items-center gap-2 overflow-hidden text-xs',
+                draggable && 'cursor-grab active:cursor-grabbing',
+                inContainer
+                    ? 'h-full min-w-0 grow text-text'
+                    : clsx(
+                          'h-10 shrink-0 border-b border-border pr-1.5',
+                          !tabs && 'pl-2',
+                          focused ? 'bg-surface text-text' : 'bg-surface-idle text-text-muted'
+                      ),
+                className
+            )}
+            onPointerDown={(event) => {
+                setGrabbable(!(event.target as HTMLElement | null)?.closest(CONTROLS));
+                props.onPointerDown?.(event);
+            }}
+            onPointerUp={(event) => {
+                setGrabbable(true);
+                props.onPointerUp?.(event);
+            }}
+            onDragStart={onDragStart}
+            onDragEnd={onDragEnd}
+        >
+            {/* The title gives way first, down to its glyph. With tabs, the strip takes its place. */}
+            <span
+                data-pane-title=""
+                className={clsx(
+                    'ade-pane-title flex items-center gap-2',
+                    tabs ? 'min-w-24 self-stretch' : 'min-w-5',
+                    /* In a container the first text stands as far after the separator as the text before it
+                       stands before it: 16 pixels, of which the gap brings 8 and a tab 12 of its own. */
+                    inContainer ? (tabs ? '-ml-1' : 'pl-2') : !tabs && 'pl-1',
+                    // A weight rather than `shrink`, since controls whose labels truncate shrink as well.
+                    tabs || ((folded || !hasActions) && !inContainer) ? 'grow' : 'shrink-100'
+                )}
+            >
+                {title}
+            </span>
+            {accessory}
+            {!separate && actionsPart}
+            {/* The room the title leaves in a container, which the window drags by. */}
+            {inContainer && !tabs && (folded || !hasActions) && <span aria-hidden="true" className="grow self-stretch" />}
+            {trailing}
+            {onClose && (
+                <CloseButton label={closeLabel ?? t('workspace.closePane')} kbd={closeShortcut} size="sm" className="cursor-default" onClick={onClose} />
+            )}
+        </header>
+    );
+
+    const placed =
+        menu === undefined ? (
+            header
+        ) : (
+            <ContextMenu.Root>
+                <ContextMenu.Trigger render={header} />
+                <ContextMenu.Popup>{menu}</ContextMenu.Popup>
+            </ContextMenu.Root>
+        );
+
+    return (
+        <>
+            {inContainer
+                ? createPortal(
+                      <>
+                          <Separator />
+                          {placed}
+                      </>,
+                      container
+                  )
+                : placed}
+            {separate && hasActions && (
+                <div
+                    ref={actionsBar}
+                    data-pane-actions=""
+                    className={clsx(
+                        'flex h-10 shrink-0 items-center gap-2 overflow-hidden border-b border-border px-2 text-xs',
+                        folded && 'justify-end',
+                        focused ? 'bg-surface text-text' : 'bg-surface-idle text-text-muted'
+                    )}
+                >
+                    {actionsPart}
+                </div>
+            )}
+        </>
+    );
+}

package/src/workspace/Workspace.tsx

@@ -1,7 +1,7 @@
-import { type ReactNode } from 'react';
+import { useState, type ReactNode } from 'react';
 import clsx from 'clsx';
 import { useRender } from '@base-ui/react/use-render';
-import { WorkspaceContext, type WorkspaceLayout } from './context.ts';
+import { TopRowSlotContext, WorkspaceContext, type WorkspaceLayout } from './context.ts';
 
 export interface WorkspaceProps extends useRender.ComponentProps<'div'> {
     layout?: WorkspaceLayout;
@@ -9,6 +9,9 @@ export interface WorkspaceProps extends useRender.ComponentProps<'div'> {
     sidebar?: ReactNode;
     sidePanel?: ReactNode;
 
+    /** A column at the window's right edge, after the side panel, usually a `WorkspaceRail`. */
+    rail?: ReactNode;
+
     /** Auto-sized regions keep their own width, separators and opening animation. */
     sidebarWidth?: number | 'auto';
 
@@ -19,11 +22,13 @@ export interface WorkspaceProps extends useRender.ComponentProps<'div'> {
 
 const isPresent = (node: ReactNode): boolean => node !== undefined && node !== null && node !== false;
 
+/** The sidebar, the toolbar and the content on one raised sheet, with the side panel and the rail behind it. */
 export function Workspace({
     layout = 'standard',
     toolbar,
     sidebar,
     sidePanel,
+    rail,
     sidebarWidth = 248,
     sidePanelWidth = 320,
     sidebarOpen,
@@ -37,9 +42,11 @@ export function Workspace({
 }: WorkspaceProps) {
     const hasSidebar = isPresent(sidebar);
     const hasPanel = isPresent(sidePanel);
+    const hasRail = isPresent(rail);
     const leftOpen = hasSidebar && (sidebarOpen ?? true);
     const rightOpen = hasPanel && (sidePanelOpen ?? true);
     const hasToolbar = isPresent(toolbar);
+    const [topRowSlot, setTopRowSlot] = useState<HTMLElement | null>(null);
 
     const element = useRender({
         render,
@@ -53,28 +60,37 @@ export function Workspace({
             'data-toolbar': hasToolbar || undefined,
             'data-sidebar': leftOpen || undefined,
             'data-side-panel': rightOpen || undefined,
+            'data-rail': hasRail || undefined,
             children: (
                 <>
-                    {hasSidebar && (
-                        <aside className="ade-workspace-sidebar" data-auto={sidebarWidth === 'auto' || undefined} style={{ width: sidebarWidth }}>
-                            {sidebar}
-                        </aside>
-                    )}
-                    <div className="ade-workspace-center">
-                        {hasToolbar && <div className="ade-workspace-toolbar">{toolbar}</div>}
-                        <div className="ade-workspace-content">{children}</div>
+                    <div className="ade-workspace-sheet">
+                        {hasSidebar && (
+                            <aside className="ade-workspace-sidebar" data-auto={sidebarWidth === 'auto' || undefined} style={{ width: sidebarWidth }}>
+                                {sidebar}
+                            </aside>
+                        )}
+                        <div className="ade-workspace-center">
+                            {hasToolbar && <div className="ade-workspace-toolbar">{toolbar}</div>}
+                            <div className="ade-workspace-content">{children}</div>
+                        </div>
                     </div>
                     {hasPanel && (
                         <aside className="ade-workspace-side-panel" data-auto={sidePanelWidth === 'auto' || undefined} style={{ width: sidePanelWidth }}>
                             {sidePanel}
                         </aside>
                     )}
+                    {hasRail && rail}
                 </>
             )
         }
     });
 
-    const context = { layout, edges: { top: !hasToolbar, right: !rightOpen, bottom: true, left: !leftOpen } };
+    // The content ends at the sheet's own edge, whatever stands beside it.
+    const context = { layout, edges: { top: !hasToolbar, right: true, bottom: true, left: !leftOpen } };
 
-    return <WorkspaceContext value={context}>{element}</WorkspaceContext>;
+    return (
+        <WorkspaceContext value={context}>
+            <TopRowSlotContext value={{ slot: topRowSlot, register: setTopRowSlot }}>{element}</TopRowSlotContext>
+        </WorkspaceContext>
+    );
 }

package/src/workspace/WorkspaceRail.tsx

@@ -0,0 +1,30 @@
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { useRender } from '@base-ui/react/use-render';
+
+export type WorkspaceRailProps = useRender.ComponentProps<'nav'>;
+
+/**
+ * The column of buttons at the right edge of a `Workspace`, 48 pixels wide. Its first separator stands on
+ * the top row's bottom line when one 32 pixel button comes before it. It makes no stacking context, so a
+ * hover never covers the sheet's edge; a tooltip still rises above the sheet.
+ */
+export function WorkspaceRail({ className, render, ref, ...props }: WorkspaceRailProps) {
+    const { t } = useTranslation('ui');
+
+    return useRender({
+        render,
+        ref,
+        defaultTagName: 'nav',
+        props: { 'aria-label': t('workspace.tools'), ...props, className: clsx('ade-workspace-rail', className) }
+    });
+}
+
+export function WorkspaceRailSeparator({ className }: { className?: string }) {
+    return <span aria-hidden className={clsx('ade-workspace-rail-separator', className)} />;
+}
+
+/** Pushes what follows to the bottom of the rail. */
+export function WorkspaceRailSpacer() {
+    return <span aria-hidden className="ade-workspace-rail-spacer" />;
+}

package/src/workspace/WorkspaceTopRow.tsx

@@ -0,0 +1,37 @@
+import { useContext, type ComponentProps, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { TopRowSlotContext } from './context.ts';
+
+export interface WorkspaceTopRowProps extends Omit<ComponentProps<'header'>, 'children'> {
+    /** Before the project: room for a window's own controls, and a button that brings the sidebar back. */
+    leading?: ReactNode;
+
+    /** The project: a switcher, or a strip of project tabs. */
+    children: ReactNode;
+
+    /** Leaves out the slot a lone pane's bar goes into, as beside project tabs, which take the row. */
+    slotless?: boolean;
+}
+
+/**
+ * The 47 pixel band at the top of a `Workspace`'s sheet, as its `toolbar`: the project, and beside it the
+ * slot where the bar of a lone pane goes (`useTopRowSlot`, `PaneBar`'s `container`). The window drags by
+ * every part of it that is not a control.
+ */
+export function WorkspaceTopRow({ leading, children, slotless = false, className, ...props }: WorkspaceTopRowProps) {
+    const { register } = useContext(TopRowSlotContext);
+
+    return (
+        <header
+            {...props}
+            className={clsx(
+                'ade-workspace-top-row relative flex h-[47px] shrink-0 items-center gap-2 bg-surface pr-1.5 pl-2 text-xs text-text-muted',
+                className
+            )}
+        >
+            {leading}
+            {children}
+            {!slotless && <div ref={register} data-top-row-slot="" className="flex h-full min-w-0 grow items-center gap-2" />}
+        </header>
+    );
+}

package/src/workspace/context.ts

@@ -7,3 +7,9 @@ export const WorkspaceContext = createContext<{ layout: WorkspaceLayout; edges:
     layout: 'standard',
     edges: { top: true, right: true, bottom: true, left: true }
 });
+
+/* The element of the top row a lone pane's bar goes into, which the row registers and every pane of the workspace reads. */
+export const TopRowSlotContext = createContext<{ slot: HTMLElement | null; register(element: HTMLElement | null): void }>({
+    slot: null,
+    register: () => undefined
+});

package/src/workspace/top-row-slot.ts

@@ -0,0 +1,7 @@
+import { useContext } from 'react';
+import { TopRowSlotContext } from './context.ts';
+
+/** The slot of the `Workspace`'s top row, for `PaneBar`'s `container`, or null while there is none. */
+export function useTopRowSlot(): HTMLElement | null {
+    return useContext(TopRowSlotContext).slot;
+}