Tsubaki で書く(actor も Tsubaki)
小さい drop なら、JS を一行も書かないでいい。ops/*.tsubaki と drop.toml の [actor] だけ置くと、
build がどの drop でも同じ殻(lib の std-actor)を着せる。殻の bytes はその lib に一枚だけあって、
drop の xpi には入らない ── xpi に残るのは、その drop 自身の宣言と logic と、殻を呼ぶ数行。
drops/hello-tsubaki がそれ(ツールバーに数字、押すと増えて pref に残る)。
ここはその道の全部。はじめの一歩は GUIDE。殻で足りないときは actor.ts の道。
drop.toml の [actor]
actors = ["hello"] # src/hello/ops/*.tsubaki
[actor]
id = "hello-tsubaki@noraneko.app"
namespace = "noraHelloTsubaki"
version = "1.0.2"
matches = ["chrome://browser/content/browser.xhtml"]
run_at = "document_end" # 既定
logic が答える door は三つ。返すのは全部データで、DOM も preact も出てこない:
setup() = Dict(
"anchor" => Dict("at" => "parent", "selector" => "#nav-bar", "tag" => "hbox", "id" => "nora-hello"),
"style" => "#nora-hello label { ... }",
"prefs" => ["noraneko.hello.count"] # 見ていてほしい pref
)
start(facts) # facts = Dict("prefs" => Dict(名前 => 値), "url" => …)。最初の一枚
dispatch(action) # 次の一枚。押されたとき、pref が変わったとき(PrefChanged)
一枚 = frame(view) か frame(view, effects)。view は el(tag, props, kids) の木で、
"on:command" => Action の値は closure ではなく action そのもの(closure は postMessage を越えない)。
殻が押されたときにそれを dispatch へ渡す — そのとき、こちら側にしか分からないこと
(画面の座標、入力欄の字、押された key)を __event に入れて添える。
props はそのまま要素に渡る。inline style は "style" => Dict("width" => "320px") と Dict で
(字を連ねると ; の混入を自分で見張ることになる)。
VNode / el / frame / effect たちは std のことば(std-tsubaki-runtime 0.7.0 以上の
ops/std.tsubaki)。[deps] に std を書けば付いてくる。
置き場所
置き場所が二つ以上あるときは "anchor" の代わりに "anchors" に名前をつけて並べ、
view はその名前で答える。窓の中の離れた二か所 — タブの横の列と、#mainPopupSet の下の
<menupopup> — は一本の木にできないので:
setup() = Dict("anchors" => [
Dict("name" => "sidebar", "at" => "before", "selector" => "#tabbrowser-tabbox", "tag" => "hbox"),
Dict("name" => "menu", "at" => "parent", "selector" => "#mainPopupSet", "tag" => "menupopup")
])
view(s) = Dict("sidebar" => …, "menu" => …)
鍵を一つ取る
置き場所に "at" => "keyset" を書く。<key> は窓の keyset の直の子でないと Firefox が見てくれないので、
そこだけ selector ではなく場所の名前で言う(殻が #mainKeyset の隣に、この drop 自身の <keyset> を立てる)。
setup() = Setup(anchors = [
Anchor(name = "mark", at = "parent", selector = "#browser", tag = "hbox", id = "nora-zen"),
Anchor(name = "keys", at = "keyset", id = "nora-zen-keys")
])
view(s) = Dict("mark" => …, "keys" => el("key", Dict("combo" => "Accel+Alt+Z", "on:command" => Toggle())))
押しかたは combo の一つの字で書く。keycode / key / modifiers の三つに綴り直すのは殻で、
同じ字が drop.toml にも並ぶ:
[permissions]
keys = ["Accel+Alt+Z"]
Accel は、どこでも同じ指(Windows と Linux は Ctrl、macOS は Cmd)。F2 のように名前のある鍵と、
Z のような一文字が書ける。宣言に無い組み合わせは、その <key> だけ置かれない — 他の鍵と
view の残りはそのまま動いて、console に一行出る。入れる人の画面には
「キーボードの Accel+Alt+Z を、この drop が受け取ります」と出る。
ツールバーに置く
"at" => "toolbar"。殻が CustomizableUI の widget を一つ作って、それぞれの窓に自分のぶんを渡す:
setup() = Setup(anchors = [Anchor(at = "toolbar", area = "nav-bar", id = "nora-undo-closed-tab")])
view() = el("toolbarbutton", Dict("label" => t(:label), "on:command" => Undo()))
area は最初に置く場所で、書けるのは abi/v1.json の toolbar_areas にある名前
(nav-bar / TabsToolbar / PersonalToolbar / widget-overflow-fixed-list)。
知らない名前は nav-bar に落ちる。
そのあとどこに居るのかは、drop には分からない。 入れた人が customize mode で動かした場所を ブラウザが覚えていて、drop が言えるのは「最初はここに」だけ。減らした機能ではなく、そういう 約束 ── 位置は入れた人のもの。
片づけも drop の仕事ではない。widget はアプリに一つで、窓を一つ閉じただけで全部の窓から
ボタンが消えては困るので、外すのは drop を外す側(Drops.sys.mts)がする。
設定の一枚を持つ
"at" => "settings" を書いて、drop.toml の matches に設定の頁も足す。
about:nora:settings が、入っている drop ごとに空の箱を置いていて、その drop の一枚がそこに入る:
[actor]
matches = ["chrome://browser/content/browser.xhtml", "chrome://noraneko-settings/*"]
setup() = Dict("anchors" => [
Dict("name" => "sidebar", "at" => "before", "selector" => "#tabbrowser-tabbox", "tag" => "hbox"),
Dict("name" => "settings", "at" => "settings")
])
view(s) = Dict("sidebar" => …, "settings" => …)
置き場所のほうに行き先が書いてあるので、窓の置き場所は設定の頁に出ないし、 設定の一枚は窓に出ない。view は、どちらでも同じ名前で答えればいい。
二つの document は logic を別々に持つ(memory は分け合わない)。話が合うのは pref
のほう -- 片方が SetPref すると、もう片方は見ていた pref が動いたのを聞いて、
その場で描き直る。窓どうしが前から合っているのと、同じ仕組み。
中身はいまの語彙だけで書ける(pref を読む・書く、view を描く)ので、足したのは場所だけ。
設定の頁は HTML の document なので、そこの view は div / label / input / span
で書く(窓のほうは XUL)。要らない drop は何も書かなくてよく、空の箱は畳まれて出ない。
できること(effect)
殻が carry out できる effect は、いまのところ 18:
| effect | すること |
|---|---|
SetPref(name, value) |
設定を書く ── 宣言 prefs |
OpenURL(url) |
web の URL をタブで開く(http/https だけ) ── 宣言 open_url |
Ask(fields, action) |
事実を訊く(要る permission は facts の側) |
Measure(selector, action) |
自分が置いたものの大きさを測る |
OpenPopup(selector, x, y) |
自分が置いた menupopup を開く |
ReloadFrame(selector) |
自分が置いた窓を読み込み直す ── 宣言 web_frame |
DoCommand(name) |
ブラウザの命令を一つ実行する ── 宣言 commands |
SetTabAttr(tab, name, value) / ClearTabAttr(tab, name) |
タブに、この drop の目印 ── 宣言 tab_marks |
SetTabValue(tab, key, value) / ClearTabValue(tab, key) |
タブに、この drop の覚書 ── 宣言 tab_values |
Prompt(tab, action, value, placeholder) |
名札のところに、字を打つ欄 ── 宣言 prompt |
HideTab(tab) / ShowTab(tab) |
タブを仕舞う / また見せる ── 宣言 tabs = "write" |
SelectTab(tab) |
そのタブを選ぶ ── 宣言 tabs = "write" |
SetWindowValue(key, value) / ClearWindowValue(key) |
窓に、この drop の覚書 ── 宣言 window_values |
Log(text) |
console に一行 |
これで足りないものは actor.ts を書く(REFERENCE-ACTOR)。狭いのはわざと: この一覧が、入れる人に「この drop は何ができるか」を約束する。
ブラウザ自身の命令は DoCommand 一つで届く。名前は abi/v1.json の commands にある綴りで、
同じ名前を drop.toml にも並べる:
[permissions]
commands = ["back", "forward", "restore-last-tab"]
update(s, a::Run) = Step(s, [DoCommand("back")])
門は二つ。宣言に有ることと、表に有ること。どちらか片方でも欠けたらしない ── 綴りを間違えても、ブラウザの知らない口が開かない。入れる人の画面には、名前ではなく 表の日本語が並ぶ(「戻る、進む、閉じたタブを戻す」)。
ブラウザ自身のページを窓に出すときは、<browser> に URL ではなく 名前を書く:
[permissions]
web_frame = true
browser_pages = ["bookmarks", "history", "downloads", "library"]
el("browser", Dict("page" => "bookmarks"))
門は命令と同じ二つ ── 表に有ることと 宣言に有ること。だから drop は chrome:// の綴りを
一度も書かないし、任意の chrome: を開く口にもならない。表は abi/v1.json の browser_pages。
読み込む窓の作りも変わる。ブラウザ自身のページは remote な窓では開かないので、
殻がその場(親)で読む窓にする ── Firefox 自身のサイドバー(#sidebar)と同じ着せかた。
web の URL(src)のほうは今までどおり content の、別のプロセスの窓。
表は Floorp の mouse-gesture の 94 個から来ていて、gecko- を落とした綴りのまま。
ページを scroll する八つは content の actor が要るのでまだ無く、窓を開け閉めするものは
別の宣言になる。
タブのこと
タブは、この drop が置いたものではない。だから触れるのは 自分が付けたものだけ ──
見える目印(attr)と、残る覚書(value)、それと名札のところに出す欄。タブそのものは
id(殻がこの窓のために鋳った不透明な字)としてしか見えない。
[permissions]
tabs = "read" # 一覧を読む。開いた / 閉じた / 選ばれた を知る
tab_marks = true # 自分の目印を付ける(CSS で拾える)
tab_values = true # 自分の覚書を残す(閉じて開き直しても付いてくる)
prompt = true # 名札のところに、字を打つ欄
tabs は 段のある宣言。"read" は読むだけ、"write" はタブを選ぶ・仕舞う・また
見せるところまで。入れる人の画面には、その段の一文だけが出る。段が足りない drop は
組むところで止まる(check-drop.rb が、どの effect がその段を要っているかを言う)。
setup() = Setup(
anchors = [...],
watch = Watch(tabs = ["open", "restore", "close", "select", "dblclick"]),
tab_values = ["name"] # 読み戻す覚書の鍵
)
出来事は一つの action にまとまって来る:
Dict("__type" => "TabsChanged", "kind" => "open", "tab" => そのタブ, "tabs" => 一覧)
一枚のタブは Dict("id" =>, "index" =>, "title" =>, "url" =>, "pinned" =>, "selected" =>, "hidden" =>, "muted" =>, "discarded" =>, "group" =>, "container" =>, "values" =>)。
url は current_url も宣言した drop にだけ入る(それ以外は空の字)── Ask("url") と同じ線で、
「タブのことを読む」と「どこを見ているかを読む」は、入れる人にとって別の一文だから。
目印と覚書の名前は 短く書く。data-nora-<uuid>-name / nora.<uuid>.name に伸ばすのは殻で、
生の CSS の中の {attr} も、殻がその接頭辞に書き換える:
SetTabAttr(id, "name", "ねこ") # → .tabbrowser-tab[{attr}name]
SetTabValue(id, "name", "ねこ") # → 再起動しても、そのタブに
だから drop は自分の uuid を一度も綴らないし、二枚の drop が互いの目印を消し合うことも、 Firefox 自身の覚書を踏むことも、構造的に起きない。
Prompt は、打ち終わると Dict("__type" => action, "tab" => …, "value" => 打たれた字) で返ってくる。
Escape で閉じたときは 何も来ない(打っていた字はどこにも残らないので、届けてもすることが無い)。
タブを仕舞う、そして戻ってくるとき
タブを束にして切り替える drop(workspaces のような)は、三つを順に使う。順が大事です ── 先に選んで、あとで仕舞う。選ばれているタブは本体が仕舞わないので、逆にすると 一枚だけ残ります。
SelectTab(id) # 新しい束の、どれかを選ぶ
HideTab(id) # 前の束のぶんを仕舞う
ShowTab(id) # 新しい束のぶんを見せる
「いまどの束を開いているか」はタブ一枚に属さないので、窓の覚書に置きます
(window_values)。置き場所が窓なだけで、作法はタブの覚書と同じ:
setup() = Setup(
window_values = ["ws"], # 読み戻す鍵。start(facts) の `window` に入って届く
tab_values = ["ws"],
restore = Restore(hide_unless = "ws")
)
restore が、前回から戻ってくるタブの迎えかた。marks はその覚書を持って戻って
きたタブに同じ名前の目印を、hide_unless はその覚書が窓の覚書と違うタブを仕舞ったまま
戻します。戻ってきてから仕舞い直すのでも動きますが、そのときは 一瞬ぜんぶ見える
── 本体は戻すタブをまとめて挿すので、殻はその同じ turn の中で焼きます。だから
logic には訊かれません(worker の返事を待つ時間が無い)。決めるのは logic、するのは殻。
facts に window が入っているかどうかは、「ここは窓か」の合図でもあります。設定の頁に
同じ logic が居るとき、そちらには窓のタブが無いので。
この drop が仕舞ったタブは、drop を外すと見せて返します(タブ帯から消えたタブを戻す道が、 外した人の手元に無くなってしまうので)。窓を閉じたときは返しません ── そのときの仕舞われかたは、 その窓の姿として SessionStore が持っていくものだから。
本体の menu に行を混ぜる
"at" => "menu":
[permissions]
menu = ["tabContextMenu"]
Anchor(name = "menu", at = "menu", menu = "tabContextMenu", id = "nora-rename-tab-menu")
行は popup の 末尾に足される(本体の行は動かさない)。その menu が「何についての menu か」を
abi/v1.json が知っているので、押されたタブの目印が host に写る ── 名前のあるタブのときだけ
出したい行は、CSS の側で閉じられる:
#nora-rename-tab-menu:not([{attr}name]) .nora-rename-clear { display: none; }
popupshowing は待てないので(worker の返事を待つあいだに popup は塗られてしまう)、
ここが一往復も要らないのは、そのための形。その行から起きた action には、どのタブのことかが
__event の tab に入って届く。
要素(tag)
tag も同じように決まっている。 view が名乗れるのは殻(drops/std-actor/src/lib/vnode.ts)の ELEMENTS
にある顔ぶれだけ(箱、ラベル、ボタン、メニューの行 — どれも何も読み込まないし、何も走らせない)。
知らない tag は、その場で止まる。約束が「effect の一覧」で済むのは、要素のほうがおとなしいからで、
そこが開いていると「データと既知の殻を読めばいい」が成り立たない。
足したい要素があれば registry に PR を(読むのは、drop を読むのと同じ人たち)。
訊く(Ask と Measure)
Ask と Measure は、命令ではなく質問。logic は事実を作らない、が守りたい線なので
(新しい uuid も、いま見ているタブの URL も、drag のあとに箱が実際になった幅も、
logic には分からない)、action に穴を開けて殻に埋めさせるのではなく、訊いて、名前を
つけた action で返してもらう。返事は普通の dispatch で来る:
update(s, a::AddClicked) = Step(s, [Ask(["uuid", "url"], "AddPanel")])
# → dispatch(Dict("__type" => "AddPanel", "uuid" => …, "url" => …))
update(s, a::DragEnded) = Step(s, [Measure("#nora-webpanel-box", "SetWidth")])
# → dispatch(Dict("__type" => "SetWidth", "width" => 321, "height" => 640))
いま訊ける事実は "uuid"(新しい uuid)、"url"(いま見ているタブの URL。
http/https でなければ "")、"tabs"(この窓のタブの一覧)、"tab"(いま選ばれているタブ)。
あとの二つは tabs = "read" が要る。Measure の selector は その drop が置いた host と
その中だけを探す — 自分が描いたものを測る。
ページを読み込む窓(<browser>)
一つだけ、宣言してから使う要素がある。drop.toml の [actor] に:
[actor]
...
web_frame = true # view に <browser> を書ける
と書くと、view が browser を名乗れる。入れる人の画面には「ページを読み込む窓を置く」と
出る(actor.json の webFrame)。view が書くのはどこに置くか・何を読むかだけ:
el("browser", Dict("key" => p.id, "src" => p.url, "flex" => "1"))
type="content" / remote="true" などの「どんな窓か」を決める九つの属性は、
殻が着せる(drops/std-actor/src/lib/vnode.ts の WEB_FRAME_ATTRS)。九つあれば一つ忘れるし、
これは view を書いていて忘れてよい種類のまちがいではないので。src は OpenURL と
同じ規則で http/https だけ — ほかは空の窓になる。
key を必ず書く。preact は key で「同じもの」を見分けて、位置が変わったときに
moveBefore(取り出さない移動)で動かす。key が無いと作り直しになって、読み込んだページが
消える。この移動は std-preact-xul 1.1.0 から(<video> や、字を打っている <input> も
一緒に助かる)。
reload() や、ページの題が変わったことを logic に伝える口は、まだ無い。要るなら
actor.ts を書く道がある。
logic を分けたいとき(import)
ops/ は一枚でなくていい。分けたぶんを module にして、import と書く:
# ops/Style.tsubaki
module Style
sheet() = "…"
end
# ops/webpanel.tsubaki
import Style
setup() = Dict("style" => Style.sheet(), …)
その import の一行が、読む順を決めている。 Tsubaki の import Shapes は
「訊いた file の隣の Shapes.jl / Shapes.tsubaki を読む」だけれど、drop の logic は
file の無い worker で動く。だから 読むのは build(tooling/webext-actors/build.ts の
opsFiles): using / import の行をたどって、import されたほうを先に置く。drop が
走るときには module がもう有るので、import は何も探さずに見つける。
書き換えも貼り合わせもしない。読まれる file は、書いた人が書いた file そのまま
(xpi の source/ と同じもの)。置き場所は ops/ の中で横並び —— それが import の
探す場所だから、path を書くことも、dir を作ることも無い。
- 隣に無い名前を import したら、build が言う(実行時は何もしない)
- 互いを import していたら、build が止まる
include(...)は drop の中では動かない(worker に読む file が無い)。分けるならimport