Why Osy# · Chapter 08 · The UI model

The screen is written in the same language as the rules.

A screen is a component, and a component is ordinary Osy#: its state is fields, its behaviour is actions, its structure is a render block in which if and foreach are the language's own, and its data can be an expression over the application. Learn this small component and you can read every screen on this page.

the board example app · model/tally.osyverbatim — this file compiles

[Route("/tally")]
component Tally() {
  int count = 0;

  action Add() { count = count + 1; }

  render {
    Stack(gap: 2) {
      Text($"{count} so far");
      if (count == 0) { Text("Press the button to start."); }
      Button("Add one", onPress: Add);
    }
  }
}

In practiceA screen is a component: fields, actions and a render block, in the language the rules are in.

The screen is a component

A page that counts button presses, whole. The basic shape of a screen is all here, and every part of it is a construct you have already met in this book.

Platform.Tools.SiteGen/content/apps/board/model/tally.osyverbatim — this file compiles

[Route("/tally")]
1component Tally() {
2  int count = 0;

3  action Add() { count = count + 1; }

4  render {
    Stack(gap: 2) {
      Text($"{count} so far");
5      if (count == 0) { Text("Press the button to start."); }
      Button("Add one", onPress: Add);
    }
  }
}

A component is a piece of screen. The attribute above it gives this one a route, which makes it a page; a component without one is called from other components, the way a function is.

A field is local state. An ordinary declaration; the screen holds it while the page is open.

An action is behaviour the screen starts. It is a function; assigning to a field is how the screen changes.

The render block describes what the component presents, by calling controls: a Stack, two Texts, a Button bound to the action.

Control flow is the language's own. An if shows a line while it holds; a foreach repeats one per item. What the block presents follows the fields.

State is fields, behaviour is actions, structure is a render block. Components compose by calling one another, which the next section shows, and the rest of this page adds one idea at a time to exactly this shape.

Appearance is named, and layout is part of the call

A screen has to look like something, and the look has to be one decision rather than a hundred. A theme gives names to visual decisions: colours, radii, type sizes, lengths and breakpoints. A colour can carry a light value and a dark value on the same line.

demo/kanban/model/look/theme.osyverbatim — this file compiles

theme Studio {
  Colors {
1    Bg        = Modes.Of(light: "#F6F7F9", dark: "#0E1116");
    OnBg      = Modes.Of(light: "#16181D", dark: "#E6EAF0");
    Surface   = Modes.Of(light: "#FFFFFF", dark: "#171B21");
    Border    = Modes.Of(light: "#E3E6EA", dark: "#2A2F37");
    Subtle    = Modes.Of(light: "#6B7280", dark: "#8A94A6");
2    Accent    = "#4F46E5";
    OnAccent  = "#FFFFFF";
    LaneBg    = Modes.Of(light: "#EEF0F4", dark: "#1C212A");
  }
3  Radius   { Card = "12px"; Control = "8px"; Pill = "999px"; }
  FontSize { Caption = "12px"; Body = "14px"; Section = "16px"; Display = "26px"; }
  FontWeight { Medium = "600"; }
  Length     { LaneW = "300px"; }
4  Breakpoints { Cozy = 900; }
}

Both modes on one line. The two values are one declaration, so they cannot drift, and adding a dark mode to an app is editing the lines that already exist.

A token with one value is the same in both modes. The brand colour usually is.

Names for more than colour. Radii, type sizes, weights and lengths are tokens too, so rounded: Radius.Card is a decision made once.

A width with a name. §3 branches on it.

The names are then used where the structure is declared. Spacing, colour, radius and size are typed arguments on the control call, so the compiler checks a layout the way it checks the rest of the program. Here is a component that other components call: a lane on a board.

demo/kanban/model/board/board.osyverbatim — this file compiles

1[Composable] component Column<T>(T[] cards, string title, int count) {
  render {
2    Stack(gap: 2, p: 2, w: Length.LaneW, bg: Colors.LaneBg, rounded: Radius.Card) {
      Row(gap: 2, align: Align.Center, px: 1) {
        Text(title, fontSize: FontSize.Section, fontWeight: FontWeight.Medium);
        Text(count, fontSize: FontSize.Caption, color: Colors.Subtle, px: 2, py: 1, bg: Colors.Surface, rounded: Radius.Pill);
      }
      Stack(gap: 2) {
        foreach (var c in cards) {
3          Slot(c);
        }
      }
    }
  }
}

A component with parameters, generic over what it holds. A lane knows it stacks things; it does not know what a card looks like.

Layout is part of the call. Every argument is typed and every value is a token, so a typo is an error at the position it happened.

The caller supplies the child. The page that uses a lane decides what goes in it, so one lane serves every board.

A theme names the decisions; a call places them. Nothing else has to agree with either, because the compiler already checked both.

The width is a value, so structure can branch on it

A board has lanes; on a wide screen they sit side by side, on a phone they stack. In Osy# the available width is a value the render block can read, and a breakpoint from the theme is a name for one, so choosing a structure is an ordinary if.

demo/kanban/model/board/board.osyverbatim — this file compiles

[Composable] component Board<T>(T[] lanes) {
  render {
1    if (Layout.AtLeast(Cozy)) {
2      Row(gap: 3, align: Align.Start, overflowX: "auto", pb: 2, role: UiRole.Region, label: "Board") {
        foreach (var l in lanes) { Slot(l); }
      }
    } else {
      Stack(gap: 3, role: UiRole.Region, label: "Board") {
        foreach (var l in lanes) { Slot(l); }
      }
    }
  }
}

A breakpoint is a branch. Wide enough and the lanes are a Row; narrower and they are a Stack. Two structures from one source, and because it is control flow, a phone can get genuinely different markup.

Accessibility is in the declaration, on the element that is the region, in a vocabulary the compiler checks.

Responsive structure is the same control flow as everything else in the block. Move the breakpoint in the theme and the branch reads the new number.

A live expression ties the screen to the application

So far the tally's state has been its own. A real screen shows application data: rows, and where a workflow has got to. In Osy# that is a live var: an expression over the application that stays current. A plain field is local state; a live expression is the application's, seen from this screen.

demo/kanban/model/board/board.osyverbatim — this file compiles

component BoardPage() {
1  live var lanes = Lane.Include(l => l.Items).OrderBy(l => l.Ordinal).Take(50);

  on mount { SeedBoard(); }

2  string moved = "";

3  action Move(Card card, Lane from) {
    var next = lanes.Where(l => l.Ordinal > from.Ordinal).FirstOrDefault();
    if (next == null) { return; }
    moved = card.Title + " → " + next.Name;
    card.Lane = next;
  }

  action Save() { UnitOfWork.Commit(); }

  Card? picked;

4  live var moves = CardFlow.For(picked).Transitions;

An entity query, live. It runs on the server under the rules chapter 05 declared, and live keeps it true: a card somebody else moves lands in this list as it happens.

A plain field beside it: the tally's kind of state, local to the screen.

An action over application data. Assigning card.Lane changes the row; the live query above already reflects it.

Workflow state, queried the same way. The workflow of chapter 03 knows which transitions are legal for the picked card and who may take them, so the screen asks it, and the buttons it renders follow.

The screen is not a second description of the application. It is an expression of the application's data, rules and workflow state, in the same program.

The frame around every page is a component too

An application's chrome, its brand, navigation tree, signed-in person, search and a page's own actions, is one declaration handed to a shell. A shell is a supplied Osy# component: it takes that declaration and its slots and arranges them for a kind of application, and the same application can choose a different arrangement by naming a different shell.

A wholesale-distribution back office in a sidebar shell: six navigation sections, purchase orders open — **Sidebar**Enterprise and operational
Persistent, hierarchical navigation for an app with many areas. SidebarShell →

A service-operations console in a rail shell: an icon rail, an incident queue and an on-call aside — **Rail**Dense, power-user tools
A narrow icon rail that gives the content every pixel it can. RailShell →

The same app on a phone: a bottom tab bar with a More sheet — **Tabbed**A handful of major areas
Tabs on a desktop and a bottom bar within thumb reach on a phone, from one navigation tree. TabbedShell →

A new-claim flow in a focused shell: a vertical stepper, the current step, a summary aside — **Focused**One task at a time
A clear primary action, your position in a sequence, and a way out. FocusedShell →

The same step on a phone: step 2 of 4, with a progress bar — **Focused**One task at a time
A clear primary action, your position in a sequence, and a way out. FocusedShell →

What happens when you change it

Change the program. The screen follows.

Each of these is a thing you would do on a Tuesday. The verdict is the compiler's, not a convention's.

You do this	Verdict	Because
Change the type of a field the render reads	refused	Refused wherever it no longer fits. Every read of the field is checked, in the render block as in an action.
Change a token	compiles	Every use follows, in both modes. That is what a token is for.
Use a token the theme does not declare	refused	Refused, by name: a missing token is a compile error.
Move a breakpoint	compiles	It is a number in the theme, and the branch reads it. Nothing else changes.
Change a live query	compiles	The screen shows the new expression and stays tied to it: what it presents follows the rows the query now selects.
Rename an entity field a screen reads	refused	Refused at the read, named. The screen is part of the resolved program chapter 07 described.

Next chapter · 09Documents are dataA document a person and an agent can edit at the same time. Declare a Markdown member and the application, its editor, its agents and its search all work on one structured document.In the referenceUI referenceControls, layout, theming, reactivity — one construct per page.The samplekanbanThe board on this page, one command away.

The screen is written in the same language as the rules.

The screen is a component

Appearance is named, and layout is part of the call

The width is a value, so structure can branch on it

A live expression ties the screen to the application

The frame around every page is a component too

Four applications, one UI model

Change the program. The screen follows.