Dock

ドックエリアは、ユーザーが配置するワークスペースです。パネルはタブグループにまとめられ、グループは左右に並べたり上下に積んだりでき、左・右・下の端にあるドックは開閉やリサイズができます。タブを別のグループにドラッグするとそのグループに加わり、グループの端にドラッグするとそのグループが分割されます。パネルは移動しても、保持している内容をそのまま保ちます。DockAreaが動作を担います。フレーム単位でネイティブに実行されるタブのドラッグ&ドロップ、分割とドックのリサイズ、ドックの開閉、ズーム、ロックです。見た目はアプリ側のものです。タブ、タブバー、ハンドル、ドロップインジケーター、各パネルの内容はアプリがレンダリングしスタイルを指定するもので、エリア自体は何も描画しません。

import { mount, signal, Text, View } from "nsh";
import { Button, DockArea, type DockAreaLayout, type DockAreaRef } from "nsh/base";
import { button, buttonText, desktop, focusRing, Log, Panel, Split, ui, wide } from "./palette";

// The panels' keys and what each shows. The layout lists the keys; the app
// renders a panel's content from its key, and the content moves with it.
const titles: Record<string, string> = {
  files: "Files",
  readme: "README.md",
  main: "main.rs",
  preview: "Preview",
  terminal: "Terminal",
  problems: "Problems",
};
const lines: Record<string, string[]> = {
  files: ["src/", "  main.rs", "  lib.rs", "README.md", "Cargo.toml"],
  readme: ["# Hopper", "", "A small app with a dockable workspace."],
  main: ["fn main() {", "    hopper::run();", "}"],
  preview: ["Hopper", "A small app with a dockable workspace."],
  terminal: ["$ cargo run", "   Compiling hopper v0.1.0", "    Finished dev in 1.92s"],
  problems: ["No problems"],
};

const initial: DockAreaLayout = {
  center: {
    type: "split",
    axis: "horizontal",
    children: [
      { type: "tabs", panels: ["readme", "main"], activeIndex: 1 },
      { type: "tabs", panels: ["preview"] },
    ],
    sizes: [null, 260],
  },
  left: { layout: { type: "tabs", panels: ["files"] }, size: 180 },
  bottom: { layout: { type: "tabs", panels: ["terminal", "problems"] }, size: 130 },
};

function App() {
  const layout = signal<DockAreaLayout>(initial);
  const locked = signal(false);
  // What shows now, in either presentation: the layout's docks when the area
  // is wide, the drawer or sheet presented when it is narrow. It starts from
  // the layout and follows onDockOpenChange.
  const shown = signal<Record<string, boolean>>({ left: true, bottom: true });
  const events = signal<string[]>([]);
  const log = (line: string) => events.set([line, ...events()].slice(0, 4));
  let area!: DockAreaRef;

  const toolbarButton = (label: string, onPress: () => void, on?: () => boolean) => (
    <Button onPress={onPress} selected={on?.() ?? false} {...button("secondary", { size: "sm", on })}>
      <Text style={buttonText("secondary", { on })}>{label}</Text>
    </Button>
  );

  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>dock</Text>
      <Text style={{ color: ui().muted }}>
        {desktop
          ? "Drag a tab onto another group, or to a group's edge to split it"
          : "Tap Files or Terminal to open a dock; hold a tab to reorder it"}
      </Text>

      <Split
        grow
        width={720}
        inspector={
          <>
            <Panel title="docks">
              <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8 }}>
                {toolbarButton("Files", () => area.toggleDock("left"), () => shown().left)}
                {toolbarButton("Terminal", () => area.toggleDock("bottom"), () => shown().bottom)}
                {toolbarButton("Lock", () => locked.set(!locked()), locked)}
                {toolbarButton("Reset", () => layout.set(initial))}
              </View>
            </Panel>
            <Log title="events" lines={events()} minHeight={96} />
          </>
        }
      >
        <View style={{ height: wide() ? 420 : 460, ...ui().card, borderRadius: 14, overflow: "hidden" }}>
          <DockArea
            ref={area}
            class="flex-1"
            layout={layout()}
            onLayoutChange={({ layout: next }) => {
              layout.set(next);
              log("onLayoutChange");
            }}
            onDockOpenChange={({ placement, open }) => {
              shown.set({ ...shown(), [placement]: open });
              log(`${placement} ${open ? "shown" : "hidden"}`);
            }}
            onPanelActiveChange={({ panel, active }) => active && log(`${titles[panel]} shown`)}
            locked={locked()}
            // The demo's two layouts: the full workspace beside the inspector in a
            // wide window, the phone presentation in one column. Without `compact`
            // the area decides by its own width (under 600 points: compact).
            compact={!wide()}
            groupClass="flex-1"
            tabBarClass="flex-row border-b border-border"
            tabClass="group px-3 py-1.5 selected:bg-muted"
            contentClass="flex-1"
            handleClass="bg-border group-hover:bg-muted-foreground group-active:bg-primary"
            handleAccessibilityLabel="Resize"
            dockClass="bg-muted/40"
            dropIndicatorClass="rounded-(--radius) border-2 border-primary bg-primary/10"
            drawerClass="bg-background border-r border-border"
            sheetClass="rounded-t-(--radius-lg) bg-background"
            backdropClass="bg-black/30"
            renderTab={(tab) => (
              // One view inside the tab: a row holding the title and the close button.
              <View class="flex-row items-center gap-1.5">
                <Text class="text-[13px] text-muted-foreground group-selected:text-foreground">{titles[tab.panel]}</Text>
                {tab.closable && desktop ? (
                  <Button
                    onPress={() => area.closePanel(tab.panel)}
                    accessibilityLabel={`Close ${titles[tab.panel]}`}
                    class="rounded-sm px-1 hover:bg-muted active:opacity-70"
                    focusStyle={focusRing()}
                  >
                    <Text class="text-xs text-muted-foreground">×</Text>
                  </Button>
                ) : null}
              </View>
            )}
            renderDragPreview={(tab) => (
              <View class="rounded-(--radius) border border-border bg-background px-3 py-1.5 shadow-md">
                <Text class="text-[13px] text-foreground">{titles[tab.panel]}</Text>
              </View>
            )}
            renderPanel={(panel) => (
              <View class="flex-1 gap-1 p-3">
                {(lines[panel.id] ?? []).map((line) => (
                  <Text class="font-mono text-xs text-foreground">{line || " "}</Text>
                ))}
              </View>
            )}
            renderEmpty={() => (
              <View class="flex-1 items-center justify-center">
                <Text class="text-sm text-muted-foreground">Every panel is closed</Text>
              </View>
            )}
          />
        </View>
      </Split>
    </View>
  );
}

mount(App);

use nsh_base::{
    dock::{DockAreaLayout, DockLayout, DockPanel, DockPlacement, DockRegion, DockTab},
    dock_area, theme,
};
use nsh_core::prelude::*;

fn workspace() -> impl IntoElement {
    let layout = signal(
        DockAreaLayout::new(
            DockLayout::h_split()
                .child(DockLayout::tabs().panel("readme").panel("main"), None)
                .child(DockLayout::tabs().panel("preview"), Some(px(320.0))),
        )
        .with_dock(DockPlacement::Left, DockRegion::new(DockLayout::tabs().panel("files")))
        .with_dock(DockPlacement::Bottom, DockRegion::new(DockLayout::tabs().panel("terminal"))),
    );
    dock_area()
        .layout(move || layout.get())
        .on_layout_change(move |next: &DockAreaLayout| layout.set(next.clone()))
        .handle_style(|s| s.bg(move || theme().border()))
        .tab_bar_style(|s| s.flex_row().border_b_1().border_color(move || theme().border()))
        .tab_style(|s| s.px_3().py_1().selected(|s| s.bg(move || theme().muted())))
        .render_tab(|tab: &DockTab| text(tab.panel.to_string()).text_sm().text_color(move || theme().foreground()))
        .render_panel(|panel: &DockPanel| {
            text(format!("{} content", panel.id)).p_4().text_color(move || theme().foreground())
        })
}

import { mount, signal, Text } from "nsh";
import { DockArea, type DockAreaLayout } from "nsh/base";

const titles: Record<string, string> = {
  files: "Files", readme: "README.md", main: "main.rs", preview: "Preview", terminal: "Terminal",
};

function App() {
  const layout = signal<DockAreaLayout>({
    center: {
      type: "split",
      axis: "horizontal",
      children: [
        { type: "tabs", panels: ["readme", "main"] },
        { type: "tabs", panels: ["preview"] },
      ],
      sizes: [null, 320],
    },
    left: { layout: { type: "tabs", panels: ["files"] }, size: 240 },
    bottom: { layout: { type: "tabs", panels: ["terminal"] }, size: 180 },
  });
  return (
    <DockArea
      class="size-full bg-background"
      layout={layout()}
      onLayoutChange={(e) => layout.set(e.layout)}
      handleClass="bg-border group-active:bg-primary"
      tabBarClass="flex-row border-b border-border"
      tabClass="px-3 py-1.5 selected:bg-muted"
      renderTab={(tab) => <Text class="text-sm text-foreground">{titles[tab.panel]}</Text>}
      renderPanel={(panel) => <Text class="p-4 text-foreground">{titles[panel.id]} content</Text>}
    />
  );
}

mount(App);

DockAreaとそれが取る値は、Rust の nsh-base クレートである nsh/base に由来します(nsh_base::dock_area()、値はnsh_base::dock)。Rust では、dock_area() がエリアを作成します。prop ごとのセッター、イベントごとのリスナー、型付きのスタイルメソッドを備えています。DockLayout は、パネルのキー(h_split()、v_split()、tabs()、.child(layout, size)、.panel(key))でレイアウトを記述します。

#レイアウト

レイアウトは値(DockAreaLayout)で、センターと、左・右・下の各端のドック(いずれも省略可能)からなります。各リージョンは、2 種類のノードからなるツリーです。

パネルは必ずタブグループの中にあります。パネルが一つのリージョンは、一つのパネルからなるタブグループです。パネルのキーはアプリがそのパネルに付ける文字列("files"、ドキュメントの id など)で、レイアウト全体で一度だけ現れます。ドック(DockRegion)は、そのツリー(layout)、端をまたぐ方向のサイズ(size、デフォルトは 200、最小 100)、開いているかどうか(open、デフォルトはtrue)、最小サイズ未満までエッジをドラッグすると閉じるかどうか(collapsible、デフォルトはtrue)で構成されます。

すべてのノードには id があります。アプリが書くレイアウトでは id を省略でき、その場合はエリアが割り当てます。エリアが報告するレイアウトには必ず id が含まれます。報告されたレイアウトをそのまま渡し戻すと各グループの同一性が保たれ、ref のメソッドはこれを使ってグループを指定します。エリアは渡されたレイアウトの整理も行います。空のグループや分割は取り除かれ、子が一つの分割はその子に置き換えられ、同じ軸の分割の中にある分割は親に統合され、activeIndex は範囲内に収められ、二度listされたキーは最初の位置だけが残ります。報告されるレイアウトは常にこの正規の形です。

レイアウトはアプリのものです(layout)。ユーザーが行うあらゆる変更(タブの選択・ドラッグ・クローズ、分割やドックのリサイズ、ドックの開閉)は新しいレイアウト全体として報告され(onLayoutChange)、エリアはアプリが渡し戻したレイアウトを表示します。アプリ自身がレイアウトを変更するときは、新しい値を渡します。保存したレイアウトの復元や、ワークスペースを並べ替えるコマンドなどです。layout のないエリアは自前のレイアウトを保持し、defaultLayout から始まり、すべての変更を引き続き報告します。

#パネルの内容

パネルが何を表示するかはアプリ次第です。renderPanel がパネルのキー(panel.id)から内容をレンダリングします。グループ内のすべてのパネルは配置され、表示中のものだけが見えるため、タブを切り替えても各パネルの内容は保たれます。また、パネルが移動するとき(別のグループへ、ドックへ、ズームへ、そして元へ)も、同じ内容が一緒に移動します。作成されたシグナル、入力欄のテキスト、スクロール位置、Web ビューのページはすべて保持されます。エリアはパネルが最初に現れたときに一度だけレンダリングし、パネルがレイアウトから外れると(onPanelRemove)その内容を解放します。

<DockArea
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  renderPanel={(panel) => (panel.id === "terminal" ? <Terminal /> : <Editor file={panel.id} />)}
  onPanelActiveChange={({ panel, active }) => active && setTitle(panel)}
  onPanelRemove={({ panel }) => closeFile(panel)}
/>

panels は、各パネルが許可する操作をキーごとに設定します。リストにないパネルはすべてを許可します。

#タブ

各グループには、表示されるパネルごとにタブを持つタブバーがあり、タブは panels の順に並びます。renderTab はタブの表示内容(タイトル、アイコン、アプリ独自の閉じるボタン)をレンダリングします。指定しない場合、タブにはパネルのキーが表示されます。タブとしての機能はエリアが提供します。押すと選択され、ドラッグするとそのパネルが移動し、スクリーンリーダーは選択状態を持つタブとして読み上げ、tabClass の selected: クラスが表示中のタブをスタイルします。タブの値は、アプリが描画に必要とする情報を伝えます。

let area!: DockAreaRef;

<DockArea
  ref={area}
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  renderTab={(tab) => (
    <View class="flex-row items-center gap-2">
      <Text class="text-sm">{titles[tab.panel]}</Text>
      <If when={tab.closable}>
        <Button onPress={() => area.closePanel(tab.panel)} accessibilityLabel="Close" class="rounded-sm px-1 hover:bg-muted">
          <Text class="text-xs">×</Text>
        </Button>
      </If>
    </View>
  )}
  renderPanel={(panel) => <Editor file={panel.id} />}
/>

#ドラッグ&ドロップ

グループの上にドラッグされたタブは、着地する位置を示し、ドロップするとその位置に置かれます。

ドラッグがホバーしている間、エリアはパネルが占める部分(結合ならコンテンツ全体、分割なら半分)にドロップインジケーターを表示します。これはアプリがスタイルを指定するパーツ(dropIndicatorClass)で、アプリがレンダリングすれば独自のコンテンツも持てます(renderDropIndicator。渡される情報は group、分割で生まれる side、またはタブバーの index)。インジケーターは新しい位置へネイティブに移動し、イージングで滑らかに動いて、別のグループでは前のものがフェードアウトするのと入れ替わりにフェードインします(ユーザーが視覚効果の軽減を求めている場合は即座に切り替わります)。ポインターや指に追従するものもアプリ次第です(renderDragPreview)。ドロップはレイアウトの一回の変更として一度だけ報告され、何も変えないドロップは何も変更しません。

ロックされたエリア、ズームされたエリア、そしてグループの横に何もない場合のそのグループの最後のパネルは、ドラッグできません。

#ドック

ドックは、パネルもサイズも失わずに開閉できます。閉じてもツリーは保持され、開くと同じグループが同じサイズで表示されます。ドックとセンターの間のエッジは、ユーザーがドラッグしてドックをリサイズするハンドルです。ドックは最小 100 ポイント、センターも最小 100 ポイントが保たれ、折りたたみ可能なドックを 50 ポイント未満で離すと閉じ、開くときのためにサイズを保持します。エリアは常に自身の範囲に収まります。ドックはエリアが残す範囲内で size のサイズで表示され、それでも収まらないときは、ドックが他の部分とともに縮み、分割の最小サイズは譲られます。renderDock は、ドックのレイアウトの前に、ドック固有のクローム(タイトルストリップや折りたたみボタンなど)を描画します。渡される情報は placement、open、size、collapsible で、dockClass がそのフレームをスタイルします。

アプリからドックを開閉・リサイズするには、ref(toggleDock、setDockOpen、setDockSize)を使います。これらはどちらのプレゼンテーションでも動作します。または、渡すレイアウトの中でドックの open と size を書き込みます(open はフルプレゼンテーションのものです)。onDockOpenChange は、ドックが表示または非表示になるたびに報告します。これはレイアウトの open を基準に測られます(最初からコンパクトなエリアは、レイアウト上で開いている各ドックを非表示として報告します)。そのため、レイアウトの open から始めて onDockOpenChange に従うトグルは、常にドックの状態を正しく表示します。

const terminalOpen = signal(true);

<DockArea
  ref={area}
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  onDockOpenChange={({ placement, open }) => placement === "bottom" && terminalOpen.set(open)}
  renderPanel={(panel) => <Editor file={panel.id} />}
/>

<Button selected={terminalOpen()} onPress={() => area.toggleDock("bottom")} class="px-3 py-1.5 selected:bg-muted">
  <Text>Terminal</Text>
</Button>

#ズーム

ズームされたグループは、ズームアウトされるか、レイアウトから外れるまで、エリア全体を占めます(area.toggleZoom(group)、ズームアウトは area.toggleZoom())。onZoomChange は、表示中のパネル、または null を報告します。ズームはグループに属するため、表示中のパネルが閉じられて次のパネルに替わっても、ズームされたままです。zoomable: false を持つパネルは、表示中の間そのグループがズームされるのを防ぎます。

#ロック

locked は配置をそのまま保ちます。タブのドラッグ、ドロップ、クローズはできません。タブの選択、リサイズ、ドックの開閉は引き続き使えるため、ロックされたワークスペースも使えるワークスペースのままです。

#メソッド

ref={area} はエリアのメソッド(DockAreaRef)を提供します。アプリのコマンド、ショートカット、メニューで使います。各編集は、ユーザーによる編集と同様に onLayoutChange で報告されます。レイアウトにないパネル、グループ、タブインデックス、ドックを渡されたメソッドは、レイアウトをそのままにし、メソッド名と値を示す警告をログに出力します。

Rust では、エリアの component_ref::<DockArea>() と .component_ref(&r) が ref を提供し、その r.api::<DockAreaApi>() が、スネークケースの同じメソッドを持ちます。

#保存と復元

報告されたレイアウトはプレーンなデータなので、保存は JSON.stringify(layout) してストレージに書き込むことで、復元はパースした値を layout として渡すことで行えます。onLayoutChange はリサイズやタブ選択を含むすべての変更を報告するため、変更が落ち着いてからストレージに書き込んでください(報告のたびにリセットされる短いタイマーを使います)。

Rust では、DockAreaLayout::to_state と from_state が DockAreaState を読み書きします。これは gpui-base のドックも使うレイアウトのファイル形式です。

#スマートフォンと狭いウィンドウ

Dock は自身の幅に適応します。幅 600 ポイント以上のエリア(デスクトップのウィンドウ、Web、タブレット、全画面の iPad、開いた状態の折りたたみ端末)は、ワークスペース全体として表示され、タブレットのマルチペインアプリのように、分割、グループ、ドックが並んで表示されます。スマートフォンやタブレットで指を使う場合、タブのドラッグは iPadOS のドラッグ&ドロップと同様に長押しで始まるため、タブバーはスワイプでもスクロールでき、ハンドルは見た目はそのままでタッチ領域が広くなります。

幅 600 ポイント未満のエリア(スマートフォン、Slide Over の iPad、狭いデスクトップやブラウザのウィンドウ、または広いレイアウトの狭いカラム)では、iPad のスプリットビューがカラムを折りたたむように、また Material Design のサポートペインがボトムシートになるように、同じレイアウトを一画面向けに提示します。

• センターは一度に一つのグループを全サイズで表示します。タブバーにはセンターのすべての表示パネルが並び、別のグループのパネルを選択すると、そのグループが表示されます。
• 左右のドックは、その端からセンターの上に重なるドロワーとなり、幅はドックと同じです。下のドックは、高さがドックと同じシートです。アプリが表示を指示したときに(toggleDock、setDockOpen。もう一方は閉じられます)一つだけ表示され、スライドして出入りし、背景のバックドロップの押下、Escape、または戻る操作で閉じられます。コンパクトなプレゼンテーションに入った時点では、どれも表示されません。
• ドラッグされたタブ(指の場合は長押しの後、ポインターの場合はすぐに)は、タブバー内で移動して並べ替えられます。

どちらのプレゼンテーションでもすべてのパネルは配置されたままなので、切り替えても内容は保たれます。表示されているドロワーやシートはコンパクトなプレゼンテーション固有のものです。レイアウトの open はフルプレゼンテーションに属し、ドロワーの表示や非表示は onLayoutChange を報告しないため、再び広くなったエリアは、ドックを元のままの状態で表示します。onDockOpenChange は両方を報告します。フルプレゼンテーションでレイアウトの open が変わったドック、コンパクトで表示または閉じられたドロワーやシート、そしてプレゼンテーションの切り替え時に表示状態が変わった各ドックです。renderDock では、open が、そのドックが現在のプレゼンテーションで表示されているかどうかを表します。レイアウトも同じ値のままなので、600 ポイントをまたぐエリア(折りたたみ端末が開く、iPad が Split View に加わる、ウィンドウやカラムがリサイズされる)でも、すべてのパネルは元の位置に留まり、アプリが保存するレイアウトは一つで済みます。エリアの幅はレイアウトされた時点で決まり(それまではウィンドウの幅が代わりに使われます)、compact は幅の代わりにプレゼンテーションを選択します。ドロワー、シート、バックドロップはアプリがスタイルを指定するパーツ(drawerClass、sheetClass、backdropClass)で、エリアの他の部分と同様です。

<DockArea
  layout={layout()}
  onLayoutChange={(e) => layout.set(e.layout)}
  drawerClass="bg-background border-r border-border"
  sheetClass="rounded-t-(--radius-lg) bg-background"
  backdropClass="bg-black/40"
  renderTab={(tab) => <Text>{titles[tab.panel]}</Text>}
  renderPanel={(panel) => <Editor file={panel.id} />}
/>

#Props

#Events

#Parts

#Accessibility

• 各タブは、スクリーンリーダーに対して選択状態を持つタブとして扱われ、Tab と同様です。アクティブにするとそのタブが選択されます。ラベルは renderTab が描画するテキストです。
• すべてのハンドル(分割のグループ間と各ドックの端)は、handleAccessibilityLabel というラベルが付いた調整可能な要素です。分割のグループ間のハンドルは Resizable のものであり、スクリーンリーダーは一度に 10 ポイントずつ動かし、onLayoutChange で値を報告します。
• コンパクト表示では、Escape と戻る操作で、表示中のドロワーまたはシートが閉じます。

ラベル、ロール、アナウンス全般については、アクセシビリティを参照してください。

#Platform notes

• ポインター(マウス、トラックパッド、画面上でホバーするペン)は、ボタンを押したまま 4 ポイント動かすとタブをドラッグします。これはどのプラットフォームでも同じです。トラックパッド付きの iPad や、マウスのドラッグで操作する幅の狭いブラウザウィンドウも、デスクトップと同様に動作します。macOS、Windows、Linux、GPUI では、タッチスクリーン搭載ノートパソコン上の指を含め、すべての押下がポインターのものとして扱われます。
• iOS、iPadOS、Android では、指で長押ししてからタブをドラッグします。これは iPadOS のドラッグ&ドロップと同じで、タブバー上のスワイプはスクロールになります。
• デスクトップとウェブ: ハンドルには、その軸に応じたリサイズカーソルが表示されます。
• スマートフォンや幅の狭いエリア: ドロワーと下部シートを備えたコンパクト表示になります。
• どのプラットフォームでも、アプリがスタイルを指定したものが描画されます: タブ、タブバー、ハンドル、ドロップインジケーター、ドック、ドロワー、シート。