Osy#betaRun it on Osyrin: osyrin.com

Reference / UI

SettingSwitch, SettingChoice, SettingNumber — settings edited in place, each saying where its value comes from

SettingsCard(title, description) { SettingSwitch(label, value, …) · SettingChoice(label, value, options, …) · SettingNumber(label, value, unit, min, max, outOfRange, …) · SettingAlways(name, help, word, note) · SettingRow(name: …) { …your control… } } — each with help, setFor, setBy, setWhen, resetTo, onReset, lockedBy, lockedWhy, note, readOnly, saves, saveWith, onSaved (SettingNumber also words)

A card of settings, one row each: the setting's name, what it does and where its value comes from on the left — the Default chip, "Set for Alpha" with who and when and a Reset link, or Locked by an organisation's policy with why — and its control on the right. A switch or a choice saves as it changes and says "Saved · Undo"; a typed number shows Cancel and Save and checks its range on Save. Someone who may not change it reads the value as words. Every colour, line, height and padding is a theme token, so a look sets its values and forks nothing.

preview1 example compiled by CIuikitsettingscontrols

Summary#

A product's settings are read far more often than they are changed, so each row says, at a glance, what the setting does and where its value comes from — and lets the person who may change it do so where it stands, without a form and a Save at the foot of the page.

SettingsCard("Designer tools", description: "What the design agent may look up.") {
  SettingSwitch("Other products", value: p.SearchOthers, help: "Search the plans of other products you can see.",
                setFor: p.SearchOthers ? "" : p.Name, onReset: ResetOthers);
  SettingNumber("Session size", value: p.SessionSize, unit: "tokens", min: 10000, max: 1000000,
                setFor: p.SessionSize == 200000 ? "" : p.Name, resetTo: "200,000", onReset: ResetSize);
  SettingSwitch("Earlier sessions", value: p.SearchSessions, lockedBy: "Northwind Health's policy · version 5",
                lockedWhy: "Session history is kept for audit.");
}

Signature#

SettingsCard(string title, string description = "") { …rows… }

SettingSwitch(string label, Binding<bool> value, string onWord = "On", string offWord = "Off", …where it comes from…)
SettingChoice<T>(string label, Binding<T> value, T[] options = T.Members, …where it comes from…,
                 Func<T, string>? detail = null, Func<T, string>? words = null)   // the kit's SelectField, in a setting's face; detail: opens its list
SettingNumber(string label, Binding<int> value, string unit = "", int min, int max, string outOfRange = "", …where it comes from…)
SettingAlways(string name, string help = "", string word = "Always on", string note = "")
SettingRow(name: "…", …where it comes from…) { YourControl(…); }

// where it comes from, and how it saves — the same on every row:
//   string help, string setFor, string setBy, string setWhen, string resetTo, Action? onReset,
//   string lockedBy, string lockedWhy, bool readOnly,
//   SettingSaves saves = SettingSaves.Immediate, Func<string>? saveWith, Action? onSaved
public enum SettingSaves { Immediate, Explicit }

Description#

One row, four ways to say where its value comes from#

Under the name and the help line, every row says where its value comes from, in exactly one of four ways. The words are the app's; the row only draws them.

The app passesThe row says
nothingthe Default chip
setFor: "Alpha" (+ setBy, setWhen, onReset, resetTo)Set for Alpha · "by you · just now" · Reset to default (or Reset to 200,000). A switch says Turned on for Alpha / Turned off for Alpha
lockedBy: "Northwind Health's policy · version 5" (+ lockedWhy)🔒 Locked · "by Northwind Health's policy · version 5", the reason under it, and the control disabled
SettingAlways(…, note: "…")the note, and "✓ Always on" where a control would be — a fact nobody changes

readOnly: true is the form for someone who may not change the setting: the value as plain words on the right ("Ask each time", "150,000 tokens", "On"), the provenance as before, no Reset and no control. Pass it from the same rule the row's security { } uses (readOnly: !IsOwner) — the row is refused by its own rules either way.

It saves where it stands#

With saves: SettingSaves.Immediate (the default) the row saves itself:

  • A switch or a choice saves as it changes, and says "✓ Saved · Undo". Undo saves the value before.
  • A typed number stays in its box until Save. Cancel and Save appear under it once the person types; Save checks min/max and says outOfRange (or "Enter a number from 10,000 to 1,000,000.") under the box, storing nothing.
  • It saves by committing the page's unit of work — or, with saveWith, through a function of the page's that answers "" when it saved and the reason when it did not, exactly as SaveBar's saveWith ([[ui-settings#save]]). A save that is refused is put back, and the reason is said under the control. onSaved runs once a save lands — to re-read who changed it and when.

saves: SettingSaves.Explicit fits the row into a page that saves with SaveBar: the control edits the page's unit of work and saves nothing itself — no "Saved", no row Save. Keep one page to one of the two.

Asking why: reason:#

reason: why (a string of the page's) draws a Why box under the control — a number's while it is typed, beside its Cancel and Save; a switch's and a choice's always, so it is filled before the press. What is typed lands in why, and the row's saveWith reads it, so an app whose server function refuses a change without a reason is answered:

string why = "";
string SaveWithReason() { return why.Trim() == "" ? "say why this is changed." : Save(why); }   // "" when it saved
SettingNumber("Session size", value: p.SessionSize, unit: "tokens", reason: why, saveWith: SaveWithReason);

The row says the app's refusal as "Not saved — say why this is changed." and the value is put back. reasonRequired: true holds the save in the kit instead, saying "Say why first." while the box is empty. Without reason nothing is drawn. In a test: Ui.Fill("Why", "Cheaper sessions", within: "Session size").

A line under the row: note:#

note: "Latest reason: cheaper sessions" on SettingSwitch, SettingChoice and SettingNumber puts the app's own words on the row's provenance line (SettingAlways and SettingRow(name:) already took it). Nothing is drawn without it.

A read-only number in the app's own words: words:#

A read-only SettingNumber says "150,000 tokens" by default. words: n => n + " dollars" says the app's own words for the value instead — a budget reads "8 dollars", not "8" or "$8.00". It is a display formatter, so no currency or unit is the kit's, exactly as SettingChoice's words: is for its options. A row that can be edited keeps its number and unit.

An app that cannot say where a value came from: chipless:#

With no setFor and no lock a row says Default. An app whose readers cannot see the change history must not say that when it is not known: chipless: true — on SettingSwitch, SettingChoice, SettingNumber and SettingRow(name: …) — leaves the Default chip out. A row that is set for something, or locked, still says so.

A control of your own in the same row#

SettingRow(name: "Colour", hint: "…", setFor: …) { ColourPicker("Colour", value: p.Colour); } lays out any control the kit does not draw in place in the same row, with the same provenance line. Without name: a SettingRow is what it always was — a control with its hint under it ([[ui-settings#row]]).

On a phone, a choice and a number go full-width#

Below the Tablet breakpoint (the row's own room, Layout.AtLeast, Viewport.AtLeast and Layout.AtLeast — the window, or the room this component has) a switch stays beside the name at 44 × 26; a choice and a number go full-width under the help line, 44 high; the provenance line comes last.

Every measure is a token#

Each defaults to a token the kit already had, so on the floor the rows take the app's theme as it is; a look that draws them to a design sets only the ones its design states differently.

TokenDefaultWhat it draws
Colors.SettingsCardBg · SettingsCardLineSurface · CardLinea settings card's ground and edge
Radius.SettingsCardRadius.Lgits corners
Space.SettingsCardHeadTop · SettingsCardHeadBottom3.5 · 3 stepsthe room above and under its title
FontSize.SettingsCardTitleBodyits title
Colors.RowLineBorderthe rule between rows
Length.SettingRowColsminmax(0, 1fr) 300pxa row's two columns: the words, the control
Space.SettingRowX · SettingRowY · SettingRowGap5 · 4 · 6 stepsa row's padding, and the room between its columns
Space.SettingRowXTouch · SettingRowYTouch4 · 3.5 stepsa row's padding on a phone
Colors.SettingNameInk · FontSize.SettingName · SettingNameTouchOnSurface · Label · Bodythe name (and a read-only value)
Colors.SettingHelpInkMetaTextthe help line, a switch's word, a lock's reason
Colors.ProvenanceInkMetaText"by you · just now", a number's unit
Colors.SettingDefaultTint · SettingDefaultInkDefaultTint · DefaultInkthe Default chip
Colors.SettingSetTint · SettingSetInkPrimaryTint · PrimaryInkthe Set for … chip
Colors.SettingLockedTint · SettingLockedInkWarningTint · WarningInkthe Locked chip
Length.SettingChipH · Space.SettingChipX · Radius.SettingChip · FontSize.SettingChipFont18px · 1.5 steps · Radius.Sm · Overlinethe chip's height, sides, corners and words
Colors.SettingSwitchOn · SettingSwitchOff · SettingSwitchKnobPrimary · ControlBorder · whitethe switch's track, on and off, and its knob
Colors.SettingSwitchLockedOn · SettingSwitchLockedOffthe on track mixed 40 % into Surface · Muteda switch a policy holds
Length.SettingSwitchW · SettingSwitchH · SettingKnobSize34px · 20px · 14pxthe switch
Length.SettingSwitchWTouch · SettingSwitchHTouch · SettingKnobSizeTouch44px · 26px · 20pxthe switch on a phone
Space.SettingSwitchInset · Shadow.SettingKnobLift3px · a 1px dropthe knob's inset and its shadow
Colors.ControlBorder · Radius.SettingControlBorder · Radius.Mda choice's and a number's box
Length.SettingControlH · SettingControlHTouch · SettingFieldWControlSm · Touch · 220pxits height (on a phone) and width
FontSize.SettingControlFont · SettingControlFontTouchLabel · Bodythe words in it, a switch's word
Colors.SelectChevronInk · Length.SelectChevronRoomMetaText · 30pxa choice's chevron and the room its box keeps clear for it — the kit's one dropdown chevron, shared with every SelectField (a choice IS a SelectField in the setting's face)
Colors.SettingLockedRowBg · SettingLockedBgMuted mixed 35 % into Surface · LockedValueBga locked row's ground, a locked box's
Colors.SettingSavedInk · SettingAlwaysTickSuccessInk · Success"Saved · Undo", the tick beside "Always on"

In a test: press a switch by its name (Ui.Click("Other products")), read a row as the group of that name (Assert.Visible("Saved", within: "Other products")), fill a number and save it in its row (Ui.Fill("Session size", "150000"), Ui.Click("Save", within: "Session size")), and Assert.Disabled a locked one.

Examples#

A product's planning settings, changed where they stand#

public enum Unfinished { [Label("Ask each time")] Ask, [Label("Move to the next release")] NextRelease }

entity ProductSettings {
  [Required, MaxLength(80)] string Product = "Alpha";
  Unfinished Unfinished = Unfinished.Ask;
  int SessionSize = 200000;
  bool SearchOtherProducts = true;
  bool SearchSessions = true;
  security { allow read, create, update when IsAuthenticated; }
}

[Route("/settings")] [Title("Settings")]
component ProductSettingsPage() {
  live var s = ProductSettings.FirstOrDefault();

  action ResetUnfinished() { s.Unfinished = Unfinished.Ask; UnitOfWork.Commit(); }
  action ResetSize() { s.SessionSize = 200000; UnitOfWork.Commit(); }
  action ResetOthers() { s.SearchOtherProducts = true; UnitOfWork.Commit(); }

  render {
    if (s != null) {
      Stack(gap: 4, p: 6) {
        SettingsCard("Planning and releases", description: "How " + s.Product + " plans its work.") {
          SettingChoice("Unfinished items at release", value: s.Unfinished,
                        help: "What happens to items that aren't done when a release is marked as released.",
                        setFor: s.Unfinished == Unfinished.Ask ? "" : s.Product, onReset: ResetUnfinished);
          SettingNumber("Session size", value: s.SessionSize, unit: "tokens", min: 10000, max: 1000000,
                        help: "The largest estimate a slice can have and still fit in one agent session.",
                        setFor: s.SessionSize == 200000 ? "" : s.Product, resetTo: "200,000", onReset: ResetSize);
        }
        SettingsCard("Designer tools", description: "What the design agent may look up.") {
          SettingAlways("Work on the outline", help: "Read and edit the outline.",
                        note: "Always available: this is the designer's core job.");
          SettingSwitch("Other products", value: s.SearchOtherProducts,
                        help: "Search the plans of other products you can see.",
                        setFor: s.SearchOtherProducts ? "" : s.Product, onReset: ResetOthers);
          SettingSwitch("Earlier sessions", value: s.SearchSessions, help: "Search this design's previous sessions.",
                        lockedBy: "Northwind Health's policy · version 5",
                        lockedWhy: "Session history is kept for audit. Ask an organization admin to change it.");
        }
      }
    }
  }
}

The kit's own test app draws the same page at /setting-controls (with the change trail's "by … · just now" and a read-only form for someone who may not change it), and its tests press, undo, refuse and lock it.

See also#

Related

SettingsArea — an app's settings: sections, explicit save and discard, undo, who changed what

The kit's settings vocabulary: `SettingsArea` lays out an app's settings — its sections in a grouped nav, the current…

[Settings] and [Setting]: a settings section declared on its row, each field drawn by its type

Mark the row staff configure `[Settings("Title", Authorize = Policy)]` and each field on it `[Setting("Label")]`, and…

Save, discard, undo — three ways to show a page's unit of work

Every edit on a page joins the route's unit of work; how the page OFFERS to keep it is a choice of presentation…

theme tokens

A `theme` block names your app's design tokens — colors, spacing, radii, and more — as reusable values. A token can…

Osysharp.Ui (the UI kit)

The bundled UI kit — ready-made styled controls like `Button`, the shared design-system vocabularies (`Tone`, `Size`)…

Viewport.AtLeast and Layout.AtLeast — the window, or the room this component has

Two questions with one shape. `Layout.AtLeast(Tablet)` asks whether THIS component's container is at least the…