Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-ui

Source of release 0.19.6

0.19.6 / src / widgets / parameters / module.lucb

#==============================================================================================
#
#   widgets/parameters/module - The ParameterPanel: specs, stored rows, lifetime and type
#
#==============================================================================================
#
#   DESCRIPTION:
#       A parameter editor after Houdini's parameter pane and Maya's Attribute
#       Editor: one compact row per parameter, a right-aligned label in a
#       resizable column, then the control. A panel is built from ParameterSpecs
#       (a name, label, kind, default, ranges, flags, conditions, doc) and draws
#       every row itself, so only the rows that show do any work and a hundred
#       parameters stay cheap. One spec makes a standalone row. The methods are
#       split by concern across the fragments, each under `extend ParameterPanel:`.
#       In ORDER:
#
#       module.lucb    the kinds, the spec, the stored row, the panel's state and lifetime
#       values.lucb    the public API: values by index or name, visibility, conditions, signals
#       arrange.lucb   placing rows into lines, the label column, and the parts of a row
#       paint.lucb     drawing the rows: labels, fields, sliders, toggles, menus, swatches
#       input.lucb     pointer gestures: scrubbing, the value ladder, clicks, the context menu
#       editing.lucb   typing into a field, keys, Tab between fields, and polled popups
#       popups.lucb    the value ladder, a small popup beside the row tooltip
#       ramps.lucb     ramp rows' data: the public calls, adding, moving and removing points
#       ramp_view.lucb ramp rows on screen: their parts, the curve or gradient, presses and drags
#
#==============================================================================================

from luce_gpu import gpu
from luce_window import input
import interop
from luce_std import math
from luce_std import ramp as ramps
import memory
import ownership
import strings
import time
from luce_color import transfer
import layout
import result
import text.cells as cell_widths
import widgets.parameter_text
from layout import Widget, Layout, Size, Constraints, Event, Rect
from painter import Painter
from theme import Theme, srgb_decoded
from geometry import Point
from font import Font, selected_font
from command import Command, command_type
from text.line_input import LineInput
from widgets.action_popup import ActionPopup, action_popup_type
from widgets.color_editor import ColorEditor, color_editor_type
from widgets.number_field import format_number
from widgets.tooltip import Tooltip, TipWait, tooltip_type
import measures
from measures import Unit
import icons

## What a parameter row edits and how it shows. Houdini's parameter types,
## less animation: `number` a float and `integer` a whole number (a field and
## an optional slider), `vector` 2–4 floats on one row, `toggle` a checkbox,
## `menu` a choice of `items`, `text` a line of text, `path` a file path with a
## browse button, `color` an RGB swatch with three fields, `button` an action,
## `separator` a rule, `folder` a collapsible heading over the rows after it,
## `info` read-only text, `swatches` a row of color chips choosing one of
## `items` (`label=#RRGGBB` each; the value is the chip's index), and
## `ramp` and `color_ramp` Houdini's ramps: a curve over 0..1 or a gradient,
## edited by its points, kept as luce-std `ramp` data (see `set_ramp`).
pub enum ParameterKind as u8:
    number = 0
    integer = 1
    vector = 2
    toggle = 3
    menu = 4
    text = 5
    path = 6
    color = 7
    button = 8
    separator = 9
    folder = 10
    info = 11
    swatches = 12
    ramp = 13
    color_ramp = 14

## One parameter as the host describes it. Only `name` and `kind` are needed;
## every other field has a default. Texts are copied when the panel takes it.
pub struct ParameterSpec:
    ## The key the host finds it by, and what conditions name.
    pub var name: str = ""
    ## What the row shows; a button's caption, a folder's heading.
    pub var label: str = ""
    pub var kind: ParameterKind = ParameterKind.number
    ## A vector's components, 2..4; 0 picks the kind's own (3 for vectors and colors).
    pub var components: i64 = 0
    ## The default: the first component, a toggle's 0 or 1, a menu item's value.
    pub var value: f64 = 0.0
    ## The other components' defaults, for vectors and colors.
    pub var y: f64 = 0.0
    pub var z: f64 = 0.0
    pub var w: f64 = 0.0
    ## The hard range: nothing typed, dragged or set goes past it.
    pub var minimum: f64 = -1.0e9
    pub var maximum: f64 = 1.0e9
    ## The slider's range, which typing may exceed; equal ends use the hard range.
    pub var soft_minimum: f64 = 0.0
    pub var soft_maximum: f64 = 0.0
    ## How far a drag, an arrow or a ladder rung moves; 0 picks one from the kind and decimals.
    pub var step: f64 = 0.0
    pub var decimals: i64 = 3
    ## A unit shown after the number, muted: "°", " px", "%".
    pub var suffix: str = ""
    ## The unit a length shows and is typed in (`millimeters()`, `inches()`):
    ## the value, ranges and step above stay in the stored unit, and the unit's
    ## suffix replaces `suffix`. `Unit()`, the default, shows the number as stored.
    pub var units: Unit = Unit()
    ## A slider beside the field (numbers and integers).
    pub var slider: bool = false
    ## The slider's track as a gradient instead of a fill: sRGB stops, `|`
    ## between them, spread evenly from the low end ("#3B7DD8|#FFFFFF|#E7A03F"
    ## for a white balance's temperature); at most eight.
    pub var gradient: str = ""
    ## A menu's items, `|` between them, each `label` or `label=value`.
    pub var items: str = ""
    ## A text or path's default, an info row's text.
    pub var text: str = ""
    ## The tooltip, shown when the pointer rests on the row.
    pub var doc: str = ""
    ## Houdini conditions, `{ shape != 2 }`: the row hides, or dims and ignores
    ## input, while one holds.
    pub var hide_when: str = ""
    pub var disable_when: str = ""
    ## Share this row's line with the next parameter, as Houdini's "join to next".
    pub var join: bool = false
    ## A folder starts open.
    pub var open: bool = true
    ## A color's or a color ramp's components are linear light rather than sRGB-encoded.
    pub var linear: bool = false
    ## The host's own number for the parameter (a slot), returned by `tag`.
    pub var tag: i64 = 0
    ## Whether the row has a default to mark changes from and revert to; a
    ## layer's name or a page chooser has none.
    pub var resettable: bool = true

## A parameter as the panel keeps it: owned texts, values and where it was placed.
struct Row:
    var kind: ParameterKind
    var name: interop.Owned[str]
    var label: interop.Owned[str]
    var suffix: interop.Owned[str]
    ## The unit shown, its suffix kept in `suffix`.
    var units: Unit
    var items: interop.Owned[str]
    var doc: interop.Owned[str]
    ## The current text of a text, path or info row; a button's caption is its label.
    var text: interop.Owned[str]
    var fallback: interop.Owned[str]
    var hide_when: interop.Owned[str]
    var disable_when: interop.Owned[str]
    var components: i64
    ## The slider's gradient stops (linear light) and how many there are.
    var stops: gpu.Color[8]
    var stop_count: usize
    var values: f64[4]
    var defaults: f64[4]
    ## A ramp row's luce-std ramp data and its default, heap arrays; the selected point.
    var ramp: f64[]
    var ramp_default: f64[]
    var point: i64
    var minimum: f64
    var maximum: f64
    var soft_minimum: f64
    var soft_maximum: f64
    var step: f64
    var decimals: i64
    var slider: bool
    var join: bool
    var linear: bool
    var tag: i64
    var resettable: bool
    ## Hidden or disabled by the host, and by the row's conditions.
    var hidden: bool
    var disabled: bool
    var hidden_when: bool
    var disabled_when: bool
    ## The folder row the row sits under, or -1; a folder's own open state.
    var folder: i64
    var open: bool
    ## Placed by `arrange`: shown, its top, height and the control's span; a
    ## joined row after the first shows its label inline at `label_x`.
    var shown: bool
    var y: f64
    var height: f64
    var control_x: f64
    var control_width: f64
    var label_x: f64

## What part of a row a point is over.
let part_none: i64 = 0
let part_label: i64 = 1
let part_field: i64 = 2
let part_slider: i64 = 3
let part_toggle: i64 = 4
let part_menu: i64 = 5
let part_browse: i64 = 6
let part_swatch: i64 = 7
let part_button: i64 = 8
let part_folder: i64 = 9
let part_chip: i64 = 11
## A ramp's curve or gradient, where its points are pressed, added and dragged.
let part_curve: i64 = 12

## Which popup is open for which row: none, a menu parameter's items, the context menu.
let popup_none: i64 = 0
let popup_items: i64 = 1
let popup_context: i64 = 2
## A ramp point's interpolation.
let popup_interpolation: i64 = 3

## A tooltip shows after the pointer rests this long on a row (nanoseconds), unless set.
let row_tip_delay: u64 = 600000000

## Room between lines, and between parts of a line.
let line_gap: f64 = 2.0
let part_gap: f64 = 4.0

## The value last copied from any panel, for Paste Value (Houdini's Copy Parameter).
var copied: f64[4]
var copied_count: i64 = 0

## A column of parameter rows. `on_change` hears every value change, live while
## a drag goes on (coalesced to one per frame); `on_begin` and `on_commit`
## bracket each user edit, a drag or a typed value or a click, so a host makes
## it one undo step; `on_action` hears buttons and browse buttons. Setting
## values from code reports nothing.
pub struct ParameterPanel: Widget:
    let box: interop.Reference[Layout]
    let font: interop.Reference[Font]
    var rows: Row[]
    var total: usize
    let changed: interop.Signal[i64]
    let began: interop.Signal[i64]
    let committed: interop.Signal[i64]
    let activated: interop.Signal[i64]
    ## Told a folder's index when the user opens or closes it (`on_folder`).
    let folded: interop.Signal[i64]
    let items_popup: interop.Reference[ActionPopup]
    let color_popup: interop.Reference[ColorEditor]
    let tip: interop.Reference[Tooltip]
    let ladder: interop.Reference[ValueLadder]
    var input: LineInput
    ## The label column's width when the host or a drag set it; 0 fits the labels.
    var fixed_label: f64
    ## Room left and right of the rows, and half of it above and below.
    var margin: f64
    ## Folder headings at a row's height with a hairline between them, for long
    ## columns of sections (a photo editor's develop panel).
    var dense: bool
    ## Folders the user closed, by name, as `|name|name|`: remembered across `set_specs`.
    var closed: interop.Owned[str]
    ## The width rows were placed for, and whether placing is due.
    var placed_width: f64
    var stale: bool
    ## Under the pointer.
    var hot_row: i64
    var hot_part: i64
    var hot_component: i64
    ## A press under way: where, what it pressed, and the values it started from.
    var press_row: i64
    var press_part: i64
    var press_component: i64
    var press_x: f64
    var press_y: f64
    var press_values: f64[4]
    ## The rate a scrub moves at; a modifier pressed mid-drag changes it from where the pointer is.
    var press_rate: f64
    var scrubbing: bool
    ## The middle-button value ladder: its rung and where the rung was taken.
    var laddering: bool
    var rung: i64
    var rung_x: f64
    var rung_values: f64[4]
    ## The field being typed in, or -1; its component.
    var edit_row: i64
    var edit_component: i64
    ## The row an edit began on (`on_begin` sent, `on_commit` due), a change
    ## waiting for the frame, and the row the keyboard acts on.
    var gesture: i64
    var pending: i64
    var current: i64
    ## Which popup is open, for which row.
    var popup_mode: i64
    var popup_row: i64
    var color_row: i64
    var color_shown: (i64, i64, i64)
    ## The row whose tooltip is due, and the wait before it shows.
    var tip_row: i64
    var tip_wait: TipWait

    ## A panel of `specs` in `font`; `label_width` fixes the label column (0 fits it
    ## to the labels), and `margin` is the room left and right of the rows (0 lines
    ## them up with what is above and below the panel). `dense` packs folder headings
    ## tighter.
    pub func init(specs: const ParameterSpec[], font: interop.Reference[Font]? = none, label_width: f64 = 0.0, margin: f64 = 8.0,
                  dense: bool = false) -> !:
        if not math.is_finite(label_width) or label_width < 0.0 or label_width > 4096.0:
            error(result.invalid, "a label column is 0..4096 points")
        if not math.is_finite(margin) or margin < 0.0 or margin > 64.0:
            error(result.invalid, "a parameter panel's margin is 0..64 points")
        var selected = try selected_font(font)
        errdefer selected.release()
        let box = try layout.make_layout()
        errdefer box.release()
        try box.value().set_shrink(vertical = 0.0)
        box.value().set_focusable(true)
        box.value().set_interactive(true)
        box.value().set_context_menu(true)
        let changed = try interop.Signal[i64]()
        errdefer changed.release()
        let began = try interop.Signal[i64]()
        errdefer began.release()
        let committed = try interop.Signal[i64]()
        errdefer committed.release()
        let activated = try interop.Signal[i64]()
        errdefer activated.release()
        let folded = try interop.Signal[i64]()
        errdefer folded.release()
        let placeholder = try interop.Reference[Command].adopt(new Command("-") in memory.heap, command_type, memory.heap)
        defer placeholder.release()
        let items_popup = try interop.Reference[ActionPopup].adopt(new ActionPopup([placeholder], selected) in memory.heap, action_popup_type, memory.heap)
        errdefer items_popup.release()
        let color_popup = try interop.Reference[ColorEditor].adopt(new ColorEditor(selected) in memory.heap, color_editor_type, memory.heap)
        errdefer color_popup.release()
        let tip = try interop.Reference[Tooltip].adopt(new Tooltip(selected) in memory.heap, tooltip_type, memory.heap)
        errdefer tip.release()
        let ladder = try interop.Reference[ValueLadder].adopt(new ValueLadder(selected) in memory.heap, value_ladder_type, memory.heap)
        errdefer ladder.release()
        let children: interop.Interface[Widget][4] = [items_popup.as_interface[Widget](items_popup.value()), color_popup.as_interface[Widget](color_popup.value()),
                                                      tip.as_interface[Widget](tip.value()), ladder.as_interface[Widget](ladder.value())]
        box.value().set_children(children) catch failure:
            for child in children:
                child.release()
            error(failure.code, failure.message)
        # The layout retained its children; these carriers were ours to drop.
        for child in children:
            child.release()
        var line = try LineInput()
        errdefer line.close()
        var empty: Row[]
        self.box = box
        self.font = selected
        self.rows = empty
        self.total = 0
        self.changed = changed
        self.began = began
        self.committed = committed
        self.activated = activated
        self.folded = folded
        self.items_popup = items_popup
        self.color_popup = color_popup
        self.tip = tip
        self.ladder = ladder
        self.input = line
        self.fixed_label = label_width
        self.margin = margin
        self.dense = dense
        self.closed = interop.Owned[str]("")
        self.placed_width = -1.0
        self.stale = true
        self.hot_row = -1
        self.hot_part = part_none
        self.hot_component = 0
        self.press_row = -1
        self.press_part = part_none
        self.press_component = 0
        self.press_x = 0.0
        self.press_y = 0.0
        self.press_values = [0.0, 0.0, 0.0, 0.0]
        self.press_rate = 0.0
        self.scrubbing = false
        self.laddering = false
        self.rung = 0
        self.rung_x = 0.0
        self.rung_values = [0.0, 0.0, 0.0, 0.0]
        self.edit_row = -1
        self.edit_component = 0
        self.gesture = -1
        self.pending = -1
        self.current = -1
        self.popup_mode = popup_none
        self.popup_row = -1
        self.color_row = -1
        self.color_shown = (0, 0, 0)
        self.tip_row = -1
        self.tip_wait = TipWait(row_tip_delay)
        try self.set_specs(specs)

    pub func layout() -> interop.Reference[Layout]:
        return self.box.clone()

    ## As tall as its shown rows; as wide as the labels and three fields need,
    ## less when less is given.
    pub func measure(available: Constraints) -> interop.Outcome[Size]:
        let natural = self.controls_left(480.0) + self.font.value().advance() * 30.0 + self.margin
        return result.success[Size](Size(math.min(available.width, natural), self.content_height()))

    pub func draw(target: interop.View[gpu.RenderTarget]) -> interop.Outcome[unit]:
        self.frame(target) catch failure:
            return result.failure[unit](failure.code, failure.message)
        return result.success[unit](())

    ## Each frame: take what the popups chose, send the change a drag left
    ## waiting (one per frame however fast the pointer), show a tooltip that is
    ## due, then draw the rows that show.
    func frame(target: interop.View[gpu.RenderTarget]) -> !:
        try self.poll_popups()
        try self.flush()
        try self.show_due_tip()
        try self.paint(target)

    pub func event(event: Event) -> interop.Outcome[unit]:
        self.handle(event) catch failure:
            return result.failure[unit](failure.code, failure.message)
        return result.success[unit](())

    pub func close():
        release_rows(self.rows, self.total)
        self.total = 0
        self.input.close()
        self.closed.release()
        self.changed.close()
        self.changed.release()
        self.began.close()
        self.began.release()
        self.committed.close()
        self.committed.release()
        self.activated.close()
        self.activated.release()
        self.folded.close()
        self.folded.release()
        self.items_popup.release()
        self.color_popup.release()
        self.tip.release()
        self.ladder.release()
        self.font.release()
        self.box.release()

    func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
        self.box.trace(visit, context)
        self.font.trace(visit, context)
        self.changed.trace(visit, context)
        self.began.trace(visit, context)
        self.committed.trace(visit, context)
        self.activated.trace(visit, context)
        self.folded.trace(visit, context)
        self.items_popup.trace(visit, context)
        self.color_popup.trace(visit, context)
        self.tip.trace(visit, context)
        self.ladder.trace(visit, context)
        self.closed.trace(visit, context)
        for index in 0..<self.total:
            trace_row(self.rows[index], visit, context)

pub let parameter_panel_type: interop.Type[ParameterPanel] = interop.Type[ParameterPanel]("ParameterPanel", ParameterPanel.close, ParameterPanel.trace, closeable = true, main_thread = true)

## A stored row from `spec`, its texts copied; defaults filled in for the kind.
func make_row(spec: ParameterSpec) -> Row!:
    var components = spec.components
    if spec.kind == ParameterKind.vector:
        components = between(components if components > 0 else 3, 2, 4)
    elif spec.kind == ParameterKind.color or spec.kind == ParameterKind.color_ramp:
        components = 3
    else:
        components = 1
    if not math.is_finite(spec.minimum) or not math.is_finite(spec.maximum) or spec.maximum < spec.minimum:
        error(result.invalid, "a parameter needs finite bounds with its maximum at or above its minimum")
    if spec.decimals < 0 or spec.decimals > 9:
        error(result.invalid, "parameter decimals must be 0..9")
    if not math.is_finite(spec.step) or spec.step < 0.0:
        error(result.invalid, "a parameter step must be finite and nonnegative")
    if not measures.valid(spec.units):
        error(result.invalid, "a unit needs a finite, positive scale and nonnegative lengths")
    var minimum = spec.minimum
    var maximum = spec.maximum
    if spec.kind == ParameterKind.color or spec.kind == ParameterKind.color_ramp:
        minimum = math.max(minimum, 0.0)
        maximum = maximum if spec.maximum != 1.0e9 else 1.0
    var defaults: f64[4] = [spec.value, spec.y, spec.z, spec.w]
    var no_ramp: f64[]
    var row = Row(kind = spec.kind, name = try interop.copy_text(spec.name), label = interop.Owned[str](""), suffix = interop.Owned[str](""),
                  items = interop.Owned[str](""), doc = interop.Owned[str](""), text = interop.Owned[str](""), fallback = interop.Owned[str](""),
                  hide_when = interop.Owned[str](""), disable_when = interop.Owned[str](""), components = components,
                  units = Unit(scale = spec.units.scale, millimeter = spec.units.millimeter, pixel = spec.units.pixel),
                  values = defaults, defaults = defaults, ramp = no_ramp, ramp_default = no_ramp, point = 0, minimum = minimum, maximum = maximum,
                  soft_minimum = spec.soft_minimum, soft_maximum = spec.soft_maximum, step = spec.step,
                  decimals = 0 if spec.kind == ParameterKind.integer else spec.decimals,
                  slider = spec.slider, join = spec.join, linear = spec.linear, tag = spec.tag, resettable = spec.resettable,
                  hidden = false, disabled = false, hidden_when = false, disabled_when = false,
                  folder = -1, open = spec.open, shown = false, y = 0.0, height = 0.0, control_x = 0.0, control_width = 0.0, label_x = -1.0,
                  stops = gradient_stops(spec.gradient), stop_count = stop_count(spec.gradient))
    errdefer release_row(row)
    row.label = try interop.copy_text(spec.label if spec.label.length > 0 else spec.name)
    row.suffix = try interop.copy_text(spec.units.suffix if spec.units.suffix.length > 0 else spec.suffix)
    row.items = try interop.copy_text(spec.items)
    row.doc = try interop.copy_text(spec.doc)
    row.text = try interop.copy_text(spec.text)
    row.fallback = try interop.copy_text(spec.text)
    row.hide_when = try interop.copy_text(spec.hide_when)
    row.disable_when = try interop.copy_text(spec.disable_when)
    if is_ramp(spec.kind):
        row.ramp_default = try starting_ramp(spec.kind)
        row.ramp = try copied_ramp(row.ramp_default)
    for component in 0..<4:
        row.defaults[component] = row_clamp(row, row.defaults[component])
    row.values = row.defaults
    return row

## The color of `#RRGGBB` (linear light), or none.
pub func color_of_hex(text: str) -> gpu.Color?:
    let bytes = text.bytes
    if bytes.length != 7 or bytes[0] != '#':
        return none
    var channels: f64[3]
    for channel in 0..<(usize)3:
        var value: i64 = 0
        for at in 0..<(usize)2:
            let c = bytes[1 + channel * 2 + at]
            let digit = (i64)(c - '0') if c >= '0' and c <= '9' else ((i64)(c - 'a') + 10 if c >= 'a' and c <= 'f' else ((i64)(c - 'A') + 10 if c >= 'A' and c <= 'F' else -1))
            if digit < 0:
                return none
            value = value * 16 + digit
        channels[channel] = transfer.srgb_decode((f64)value / 255.0)
    return gpu.Color(channels[0], channels[1], channels[2])

## The stops of a gradient spec, `|` between them, at most eight; malformed ones left out.
func gradient_stops(text: str) -> gpu.Color[8]:
    var out: gpu.Color[8] = ---
    for at in 0..<(usize)8:
        out[at] = gpu.Color()
    var count: usize = 0
    var first: usize = 0
    let bytes = text.bytes
    while first < bytes.length and count < 8:
        var end = first
        while end < bytes.length and bytes[end] != '|':
            end += 1
        if let color = color_of_hex((str)bytes[first..<end]):
            out[count] = color
            count += 1
        first = end + 1
    return out

func stop_count(text: str) -> usize:
    var count: usize = 0
    var first: usize = 0
    let bytes = text.bytes
    while first < bytes.length and count < 8:
        var end = first
        while end < bytes.length and bytes[end] != '|':
            end += 1
        if color_of_hex((str)bytes[first..<end]) != none:
            count += 1
        first = end + 1
    return count

## The unit row `row` shows, its suffix a view of the row's.
func row_units(row: Row) -> Unit:
    var shown = row.units
    shown.suffix = row.suffix.value
    return shown

## The decimals row `row` shows in its unit.
func shown_decimals(row: Row) -> i64:
    return measures.shown_decimals(row.decimals, row.units)

## `value` as row `row` keeps it: inside the hard range, whole for integers,
## 0 or 1 for toggles.
func row_clamp(row: Row, value: f64) -> f64:
    if not math.is_finite(value):
        return row.minimum if row.minimum > 0.0 else math.min(0.0, row.maximum)
    var kept = math.clamp(value, row.minimum, row.maximum)
    if row.kind == ParameterKind.integer:
        kept = math.floor(kept + 0.5)
    elif row.kind == ParameterKind.toggle:
        kept = 1.0 if value != 0.0 else 0.0
    return kept

func release_row(row: Row):
    row.name.release()
    row.label.release()
    row.suffix.release()
    row.items.release()
    row.doc.release()
    row.text.release()
    row.fallback.release()
    row.hide_when.release()
    row.disable_when.release()
    if row.ramp.length > 0:
        free(row.ramp) in memory.heap
    if row.ramp_default.length > 0:
        free(row.ramp_default) in memory.heap

func release_rows(rows: Row[], count: usize):
    for index in 0..<count:
        release_row(rows[index])
    if rows.length > 0:
        free(rows) in memory.heap

func trace_row(row: Row, visit: func(ownership.Object*, void*) -> unit, context: void*):
    row.name.trace(visit, context)
    row.label.trace(visit, context)
    row.suffix.trace(visit, context)
    row.items.trace(visit, context)
    row.doc.trace(visit, context)
    row.text.trace(visit, context)
    row.fallback.trace(visit, context)
    row.hide_when.trace(visit, context)
    row.disable_when.trace(visit, context)

## Replace owned text `slot` with a copy of `text`.
func replace_text(slot: interop.Owned[str]*, text: str) -> !:
    if slot.value == text:
        return
    let copy = try interop.copy_text(text)
    let previous = *slot
    *slot = copy
    previous.release()

## `value` held inside `low..high`, for whole numbers.
func between(value: i64, low: i64, high: i64) -> i64:
    if value < low:
        return low
    if value > high:
        return high
    return value

test "gradient stops and swatch colors read #RRGGBB":
    let white = color_of_hex("#FFFFFF") else trap("white did not parse")
    assert(white.red > 0.999 and white.green > 0.999 and white.blue > 0.999)
    let middle = color_of_hex("#808080") else trap("grey did not parse")
    assert(math.abs(middle.red - transfer.srgb_decode(128.0 / 255.0)) < 1.0e-9)
    assert(color_of_hex("808080") == none and color_of_hex("#80808") == none and color_of_hex("#80Z080") == none)
    assert(stop_count("#4A7FD6|#F0F0F0|#E8A93C") == 3 and stop_count("") == 0 and stop_count("#4A7FD6|nope|#E8A93C") == 2)