Calling the space

This page lists the members of os, the SDK's object for what an Orb does beyond its screen.

import { os, type ZoneEvent } from "@greyverse/orb";

onEnv, onZone, onWindow, onClosing and action are also exported on their own, with the types ZoneEvent, WindowState, Action and Send.

zone

os.zone<T>(method, args?, ids?) calls one of the space's functions for the Orb's person, as the Orb, and returns a promise. Write the method name as it is, with its ids as {…} places, and pass the ids apart. Each id must be a non-empty string without / : { } ? #, or the call is rejected with code invalid. A failure carries a code.

os.zone<Page>("rooms/{room}/messages:list", { limit: 50 }, { room });
os.zone<Message>("rooms/{room}/messages:create", { text: words, client_id: client }, { room });
os.zone<Activity>("activity/{row}:stop", undefined, { row: a.id }).then(
  () => setAsking(false),
  (e: Failure) => e.code === "forbidden" && setRefused(true),
);

onZone

os.onZone(f) gets the space's events the person may see, as { kind, room?, resource?, message?, ids? }. It returns the function that stops them.

useEffect(() => {
  const off = os.onZone((e: ZoneEvent) => {
    if (e.room !== room) return;
    if (e.kind === "message" && e.message) add(e.message as Message);
    if (e.kind === "deleted" && e.ids) drop(e.ids);
  });
  return off;
}, [room]);

env, onEnv

os.env is the environment: light or dark, density, text scale, reduced motion, language, the window's size. The base Orbs read person, zone, language and theme from it. os.onEnv(f) is told when it changes and returns the function that stops it.

const [me, setMe] = useState(String(os.env.person ?? ""));
useEffect(() => os.onEnv((e) => setMe(String(e.person ?? ""))), []);

strings, t

os.strings(table) gives the platform the Orb's words once: key → each language's text. Elements draw them by t="key". os.t(key, args?) returns one of them now, in the person's language, with {…} holes filled from args.

os.strings(strings);
os.t("time.m", { n: m });

call

os.call<T>(name, args?) calls one of the platform's own functions and is answered at once.

os.call("link.open", url);
const langs = os.call<Record<string, string>>("languages");

catalogue

os.catalogue is the design system's catalogue: every element, parameter and token, with its kind and range.

const roots = (os.catalogue as { roots: Record<string, Root> }).roots;

args, onOpen, openWindow

os.args is what this window was opened with. os.openWindow(args, how?, opts?) opens one more window of this Orb with other args:

• how: "replace" (the default, in place), "tab" or "window".
• opts.layer: "floating", "desktop" or "normal". The platform gives floating and desktop to an Orb its person installed.

os.onOpen(f) is called when the platform opens this window again for something new instead of a second window of the same place (a room's chat at another message). f gets the args it would have been opened with, in the same shape as os.args, and os.args holds them from then on. It returns the function that stops it.

const [args, setArgs] = useState(os.args);
useEffect(() => os.onOpen(setArgs), []);
const { room } = args as { room?: string };
os.openWindow({ room: id }, how);

takeInput, onInput

os.takeInput(label) takes the chat bar while the Orb's window is in focus, named label there; null gives it back. os.onInput(f) gets each line sent, as (text, { text, chips, files, settings }). A second onInput replaces the first.

useEffect(() => {
  os.takeInput(named || "…");
  return () => os.takeInput(null);
}, [named]);
useEffect(() => os.onInput((words) => send(words)), [room]);

window, onWindow, onClosing

os.window is { active, shown, width, height } for the window the Orb is in. os.onWindow(f) is told as it changes. os.onClosing(f) is asked once before the tab or window closes; returning true keeps it open.

action

os.action({ id, run, … }) declares something a person can do in the Orb. It runs the same way from a press on an element that carries it (action="id", its arguments in with), from its keys, from the platform's menu, and from agents. Declaring the same id again replaces it, and the returned function takes it away.

• label: its words; "t:key" is one of the Orb's.
• help: one line, for agents and search.
• args: each argument's kind, "string", "number", "boolean" or "a|b|c"; a trailing ? makes it optional.
• enabled: false greys it out and refuses it to agents.
• keys: its keys while the Orb is in front, e.g. "mod+enter".
• menu: its group in the menu bar.
• confirm: an agent's call waits for the person to allow it.

useEffect(() => {
  const off = (Object.keys(panes) as Pane[]).map((p) =>
    os.action({ id: `show.${p}`, label: `t:pane.${p}`, menu: "pane", run: () => setPane(p) }),
  );
  return () => off.forEach((f) => f());
}, []);

<os-button mode="icon" t={`pane.${p}`} action={`show.${p}`} />

provide, flush

os.provide(name: string, f: (arg: unknown) => unknown): void
os.flush(): void

provide takes on a place of the platform (a kind of search result …), answered by f. flush sends the screen's pending changes to the platform.