ドキュメントをモーダルの外に出しました
あなたは決済サービスのオンボーディングページを書いています。見出しが 6 つ、コードブロックが 2 つ、消費しているキューの表が 1 つ、そして何度も書き直している段落が 1 つ——次のエンジニアが実際に読むのは、その段落だからです。
Archyl では、今週まで、その全部をダイアログの中で書いていました。背後のページは暗くなります。隣接するページが並び、前のページに何という名前を付けたか確かめに行くはずのドキュメントツリーも、一緒に暗くなります。エディターはダイアログを埋め、ダイアログは画面ではなく、ページを読むこととページを書くことは、2 つの別々の場所で起きていました。
動いてはいました。ただ、あまりプロフェッショナルには感じられませんでした。腰を据えて作り直すまで、私が何度も戻ってきたのはこの一文です。
ドキュメントのワークスペースにモーダルはもうありません。 代わりに入ったものを紹介します。
エディターはドキュメントのある場所で開く
ページで 編集 を押すか、読んでいる最中に E を押すと、エディターがその場でコンテンツ列を引き受けます。ツリーは元の場所に、明るさもそのままで残り、クリックもできます。何も何かの上に重なりません。
書いている間も、ドキュメントはドキュメントのままの見た目です。タイトルは見出しサイズの素の入力欄で、ラベルも囲みの枠もありません。タグはその下にあります。入力して Enter かカンマを押せば追加、空の欄で Backspace を押せば直前のものを取り消せます。フォルダのパスはアクションバーの上端に沿って伸びるので、いま書いているページがどこに着地するかが常に分かります。
バーは状態も持っています。下書きが保存済みの内容と違っている間は琥珀色のドットと 未保存の変更、そして ⌘↵ のヒントを添えた 保存。このショートカットはエディターのどこからでも、Markdown の本文の中からでも効くので、わざわざボタンまで戻る必要はありません。段落だけを見たいときのために、モード切り替えの隣に全画面表示のトグルがあり、Escape で戻ってこられます。下端には単語数と読了時間が並びます。
執筆、分割、プレビュー
エディターには 3 つのモードがあり、ツールバーで決める必要があるのはこれだけです。
- 執筆 は Markdown だけ、列の幅いっぱいに表示します。
- 分割 はソースとレンダリングされたページを左右に並べます。
- プレビュー はレンダリングされたページだけです。
デフォルトは分割です。どれを選んでも Archyl はそれをブラウザに保存し、以降どのドキュメントもそのモードで開きます。生の Markdown で書く人と、見出しがレンダリングされるのを見たい人が、それについて言い争ったり、ページごとに設定し直したりする必要はもうありません。
フォルダはツリーの中の 1 行
フォルダを作るのは、以前は専用のダイアログでした。囲み、テキスト入力欄、作成ボタン、そしてフォルダがどこに現れようとしているのかは手がかりなし。
いまはツリーのヘッダーにあるフォルダアイコンをクリックすると、そのフォルダが実際に置かれる場所ぴったりに、正しいインデントで、フォルダアイコンもすでに描かれた状態で、編集可能な行が開きます。名前を入力して Enter を押せば、それで存在します。Escape でキャンセル。フォルダ自身のメニューからサブフォルダを求めれば、親が展開してその中に行が現れます。
名前の変更も同じやり方で、行の中で行います。ページとフォルダの移動は今までどおりドラッグ＆ドロップです。
未保存の作業からクリックで離れることはできない
ドキュメントのワークスペース内のあらゆる移動は、1 つのガードを通ります。ツリーで別のページを選ぶ、新しいページを始める、別のページを編集で開く、エディターをキャンセルする。下書きに未保存の変更があれば、その操作はいったん保留され、先に確認が出ます。逃げ道が 編集を続ける、意図してそうする側が 変更を破棄 です。確認したら、もともと頼んでいた操作が実行されます。
ブラウザもカバーしています。未保存の下書きを抱えたままタブを閉じると、ブラウザ自身の警告が出ます。
これはこのリリースでいちばん目に見えない変更であり、私がいちばん強く擁護する変更でもあります。クリックできるページのツリーをエディターの隣に置くレイアウトが良いものになるのは、クリックが段落 1 つを失わせない場合だけです。
目次はウィンドウではなくパネルに従う
列が十分に広ければ、ページの見出しはテキストの右側にある固定のレールに収まり、スクロールに合わせて現在のセクションが示されます。レールを置くには狭すぎるときは、代わりにツールバーの 目次 ポップオーバーに畳まれます。
この 2 つの切り替えを決めているのは、ブラウザのウィンドウ幅ではなくパネルの幅です。その区別こそが要点です。ドキュメントの列はツリーと場所を分け合っているので、ツリーを開いた 27 インチのモニターは、狭い読書用の列を囲む広いウィンドウということになります。ウィンドウ基準のブレークポイントなら、そこにレールを置いて文章を押し潰してしまうでしょう。Tailwind 4 のコンテナクエリが、パネル自身に自分を測らせます。
見出しをクリックすると記事がスクロールします。スクロールするのは記事だけです。レールは自分のリストをスクロールしてアクティブな項目を視界に保ち、あなたの下でドキュメントを動かしたりはしません。
山から降ろしたもの
このリリースで 4 つのコンポーネントをきれいに削除しました。ドキュメントのモーダル、フォルダ作成のモーダル、古い目次サイドバー、そしてもうどこからもレンダリングされていなかったカードリスト形式のドキュメントページです。
Markdown エディターは引き続き @uiw/react-md-editor ですが、そのスタイルは Archyl の他の部分と同じデザイントークンから来るようになりました。ライトとダークは 1 つのルールセットで、ライブラリ自身のスタイルの上にテーマごとの上書きブロックを重ねることはもうありません。
添付ファイルは変わっておらず、これまでどおり動きます。エディターにファイルをドロップする、スクリーンショットを貼り付ける、あるいは 添付 を使う。画像は本文に埋め込まれ、それ以外はすべて添付パネルに着地し、ページヘッダーのクリップの数字がそこへ飛ばしてくれます。詳しい経緯は ドラッグ、ドロップ、完了：ファイルが Archyl ドキュメントへ にあります。
テキストボックスをわざわざ作り直す理由
Archyl の仕事はアーキテクチャモデルをコードに忠実なまま保つことで、その部分はディスカバリーが自分でやってくれます。モデルの周りにある文章には、そういう助けはありません。なぜそのキューがあるのかを説明する ADR、オンボーディングページ、ランブック——それらが正しくあり続けるのは、誰かが書き続けているからにすぎません。そして書く場所が書き手と戦うとき、人は書く量を減らします。
モーダルは、毎回きっちり徴収される小さな税でした。それはもうありません。
サインインして、どのプロジェクトでも ドキュメント を開き、ページ上で E を押してください。有効にするものも、移行の手順もありません。ページもフォルダも添付ファイルも、置いたままの場所にあります。機能ガイドは ドキュメントと ADR にあります。