rgame 0.2.0 → 0.3.1

data/lib/rgame/engine/ui/panel_menu.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A menu that draws its own backdrop: a nine-slice round its buttons,
+      # grown by `padding` on every side.
+      #
+      #   column = UI::Column.new(item_width: 180, item_height: 34)
+      #   menu = layer.add_node(UI::PanelMenu.new(x: 56, y: 56, layout: column))
+      #   menu.add(UI::PanelButton.new(label: 'Resume')).on_activated { close }
+      #
+      # The panel is sized from the menu's bounds, which the layout recomputes on
+      # every `add`, so a button added later grows the panel with it — there is
+      # no count to keep in step with the buttons. The menu's origin stays the
+      # layout's origin: with a UI::Column that is the first button's corner, and
+      # the panel reaches `padding` beyond it up and to the left.
+      #
+      # The buttons are children, so they draw over the panel without a `z`.
+      class PanelMenu < Menu
+        attr_reader :panel, :padding
+
+        def initialize(panel: :panel, padding: 16, **)
+          super(**)
+          @panel = panel
+          @padding = padding
+        end
+
+        def on_draw(renderer, _view)
+          renderer.nine_slice(@panel, bounds_x - @padding, bounds_y - @padding,
+                              bounds_width + (@padding * 2), bounds_height + (@padding * 2))
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/pointing.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # Focus chosen by direction: the button a stick points at is the focused
+      # one. Built for a UI::Ring, which is what makes a radial menu.
+      #
+      #   wheel = UI::Menu.new(x: 320, y: 240,
+      #                        layout: UI::Ring.new(radius: 120, item_width: 96, item_height: 30),
+      #                        navigation: UI::Pointing.new)
+      #
+      # It reads `ui_radial_x` and `ui_radial_y` from the universal set every
+      # InputMap is merged over. They share the left stick with `move_x` /
+      # `move_y` by default and are still separate actions, so a game can move
+      # its wheel to the right stick without rebinding how its players walk.
+      #
+      # ## The button pointed at is the nearest by angle
+      #
+      # Each button's centre, seen from the menu's origin, is a direction, and the
+      # stick's direction focuses whichever button's direction is closest. On a
+      # ring centred on the origin that cuts the circle into one equal sector per
+      # button, centred on it. It asks the layout nothing: the angles come from
+      # where the buttons actually are, so a ring that starts somewhere else, or a
+      # layout that is not a ring, cannot disagree with it.
+      #
+      # ## Below the dead zone nothing is focused
+      #
+      # A stick at rest is a direction too, just a meaningless one, and a
+      # released stick springs back through the middle on its way there. So a
+      # deflection shorter than `dead_zone` focuses nothing, and a confirm in
+      # that state activates nothing — letting go of the stick and pressing A
+      # never picks whatever happened to be under it last.
+      #
+      # That dead zone is a *length*, on the combined vector, and sits on top of
+      # the per-axis one ActionMapper applies: that one takes 0.15 off each axis
+      # and rescales, and exists to stop a worn stick drifting. It is far too
+      # small to decide that a player means a direction.
+      #
+      # A disabled button is never focused, so pointing at one selects nothing.
+      #
+      # ## A grace window, for a stick that springs back
+      #
+      # `grace:` is how long, in seconds, focus survives the stick entering the
+      # dead zone before it clears. A player choosing by letting go of a
+      # trigger lets go of the stick a moment earlier, and the stick is back in
+      # the middle before the trigger comes up; the window is what lets that
+      # release still choose. Leaving the stick at rest for longer than it
+      # chooses nothing, which is the dead-zone rule again, only later.
+      #
+      # It applies to the dead zone only: pointing at a disabled button clears
+      # focus at once. Time is counted in `update(dt)`, so a paused menu's window
+      # does not run out.
+      #
+      # `GRACE`, 0.15 s, is nine frames at 60 Hz. A released stick is back in the
+      # middle within a frame or two and overshoots for about 50 ms more before
+      # its spring settles; the window covers both, plus the moment between a
+      # thumb leaving the stick and a finger leaving the shoulder button. Much
+      # longer, and centring the stick to cancel starts to feel like waiting.
+      class Pointing < Navigation
+        DEAD_ZONE = 0.5
+        GRACE = 0.15
+
+        # `grace` is what was passed, or once the menu is built, the resolved
+        # default. nil before then when none was passed.
+        attr_reader :dead_zone, :grace, :aim_x, :aim_y
+
+        # `grace: nil` resolves when the menu is built: GRACE on a menu with a
+        # trigger, which is chosen by letting go, and 0.0 on any other.
+        def initialize(dead_zone: DEAD_ZONE, grace: nil)
+          super()
+          @dead_zone = dead_zone
+          @grace = grace
+          @aim_x = 0.0
+          @aim_y = 0.0
+          @at_rest = false
+          @at_rest_for = 0.0
+        end
+
+        def attach(menu)
+          super
+          @grace = menu.trigger ? GRACE : 0.0 if @grace.nil?
+        end
+
+        # The index of the button `(x, y)` points at, or nil if the vector is
+        # shorter than the dead zone. `y` is positive downwards, like the stick
+        # and the screen. Whether that button is enabled is not this method's
+        # question.
+        def index_at(x, y)
+          return nil if Math.hypot(x, y) < @dead_zone
+
+          aim = Math.atan2(y, x)
+          nearest = nil
+          best = Float::INFINITY
+          menu.buttons.each_index do |index|
+            gap = angle_between(aim, direction_of(menu.buttons[index]))
+            next unless gap < best
+
+            best = gap
+            nearest = index
+          end
+          nearest
+        end
+
+        def on_control(actions)
+          @aim_x = actions.axis(:ui_radial_x)
+          @aim_y = actions.axis(:ui_radial_y)
+          if Math.hypot(@aim_x, @aim_y) < @dead_zone
+            @at_rest_for = 0.0 unless @at_rest
+            @at_rest = true
+            menu.focus(nil) unless @at_rest_for < @grace
+          else
+            @at_rest = false
+            index = index_at(@aim_x, @aim_y)
+            menu.focus(index && menu.buttons[index].enabled? ? index : nil)
+          end
+        end
+
+        # Counts how long the stick has been at rest, for the grace window.
+        def update(dt)
+          @at_rest_for += dt if @at_rest
+        end
+
+        # Forgets the last aim and focuses nothing, so a menu opened again does
+        # not start where the last opening left off.
+        def on_opened
+          @aim_x = 0.0
+          @aim_y = 0.0
+          @at_rest = false
+          menu.focus(nil)
+        end
+
+        private
+
+        def direction_of(button)
+          Math.atan2(button.y + (button.height / 2.0), button.x + (button.width / 2.0))
+        end
+
+        def angle_between(first, second)
+          gap = (first - second).abs % (Math::PI * 2)
+          gap > Math::PI ? (Math::PI * 2) - gap : gap
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/radial_menu.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A wheel: a Menu with its buttons on a UI::Ring and focus chosen by
+      # UI::Pointing, drawing its own backdrop disc, the dead zone to scale, and
+      # a pointer from the centre towards where the stick aims.
+      #
+      #   wheel = layer.add_node(UI::RadialMenu.new(x: 320, y: 240, radius: 150, button_width: 64))
+      #   wheel.add(UI::IconButton.new(image: :home, style: UI::ShapeStyle.new(shape: :disc)))
+      #
+      # The menu's origin is the centre of the wheel. The backdrop is sized from
+      # the ring's bounds — the square enclosing every slot, whatever the number
+      # of buttons — plus `padding`, so it does not change size as buttons are
+      # added. The pointer's tip is clamped to the ring: two arrow keys read as
+      # (1, 1), which is longer than a stick can reach.
+      #
+      # `backdrop:`, `dead_zone_color:` and `pointer:` are colours, and `nil`
+      # omits that part. The buttons are children, so they draw over all three.
+      #
+      # `trigger:` makes it the wheel held open by a button — see UI::Menu, "A
+      # menu held open by an action" — and `grace:` is its UI::Pointing's, which
+      # already defaults to `Pointing::GRACE` on a menu with a trigger.
+      #
+      # It builds its own layout and navigation, so passing `layout:` or
+      # `navigation:` raises ArgumentError: forwarded on, either would silently
+      # replace the ring or the pointing this class is made of. A wheel stepped
+      # through with the default navigation is a UI::Menu with a UI::Ring.
+      class RadialMenu < Menu
+        BACKDROP = Util::Color.new(44, 40, 52)
+        DEAD_ZONE = Util::Color.new(76, 72, 88)
+        POINTER = Util::Color.new(240, 236, 224)
+
+        POINTER_THICKNESS = 3.0
+        POINTER_TIP_RADIUS = 6
+
+        attr_reader :padding, :backdrop, :dead_zone_color, :pointer
+
+        def initialize(radius:, button_width:, button_height: button_width, dead_zone: Pointing::DEAD_ZONE,
+                       grace: nil, padding: 16, backdrop: BACKDROP, dead_zone_color: DEAD_ZONE, pointer: POINTER,
+                       **options)
+          refuse_preset_keywords(options)
+          super(layout: Ring.new(radius: radius, item_width: button_width, item_height: button_height),
+                navigation: Pointing.new(dead_zone: dead_zone, grace: grace), **options)
+          @padding = padding
+          @backdrop = backdrop&.then { Util::Color.coerce(it) }
+          @dead_zone_color = dead_zone_color&.then { Util::Color.coerce(it) }
+          @pointer = pointer&.then { Util::Color.coerce(it) }
+        end
+
+        def on_draw(renderer, _view)
+          radius = layout.radius
+          renderer.circle(0, 0, backdrop_radius, color: @backdrop) if @backdrop
+          renderer.circle(0, 0, navigation.dead_zone * radius, color: @dead_zone_color) if @dead_zone_color
+          draw_pointer(renderer, radius) if @pointer
+        end
+
+        # The radius of the disc drawn behind the ring: half the larger side of
+        # the bounds, plus `padding`.
+        def backdrop_radius
+          ([bounds_width, bounds_height].max / 2.0) + @padding
+        end
+
+        private
+
+        def refuse_preset_keywords(options)
+          return unless options.key?(:layout) || options.key?(:navigation)
+
+          raise ArgumentError, 'a RadialMenu builds its own layout: and navigation:; use UI::Menu to choose them'
+        end
+
+        def draw_pointer(renderer, radius)
+          aim_x = navigation.aim_x
+          aim_y = navigation.aim_y
+          reach = radius / [Math.hypot(aim_x, aim_y), 1.0].max
+          tip_x = aim_x * reach
+          tip_y = aim_y * reach
+          renderer.line(0, 0, tip_x, tip_y, thickness: POINTER_THICKNESS, color: @pointer)
+          renderer.circle(tip_x, tip_y, POINTER_TIP_RADIUS, color: @pointer)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/ring.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A Menu layout: items spaced evenly round a circle **centred on the
+      # menu's origin**, the first straight up and the rest clockwise.
+      #
+      #   UI::Menu.new(x: 320, y: 240, navigation: UI::Pointing.new,
+      #                layout: UI::Ring.new(radius: 120, item_width: 96, item_height: 30))
+      #
+      # Each item is centred on its point of the circle, so `radius` is the
+      # distance from the menu's origin to an item's middle. Adding an item
+      # re-spaces every item, because the gap between them depends on how many
+      # there are.
+      #
+      # Paired with UI::Pointing it is a radial menu. With the default
+      # UI::Stepping it is a ring that `ui_up` and `ui_down` step round, which is
+      # why its `axis` is `:vertical`.
+      class Ring
+        attr_reader :radius, :item_width, :item_height
+
+        def axis = :vertical
+
+        def initialize(radius:, item_width:, item_height:)
+          @radius = radius
+          @item_width = item_width
+          @item_height = item_height
+        end
+
+        def arrange(items)
+          count = items.size
+          items.each_with_index do |item, index|
+            angle = Math::PI * 2 * index / count
+            item.x = (Math.sin(angle) * @radius) - (@item_width / 2.0)
+            item.y = (-Math.cos(angle) * @radius) - (@item_height / 2.0)
+            item.width = @item_width
+            item.height = @item_height
+          end
+        end
+
+        # `[x, y, width, height]` of the square that encloses the whole circle
+        # of slots, centred on the menu's origin — not the tightest box round
+        # the items placed so far, so a backdrop keeps its size as a ring grows.
+        # All zero for no items.
+        def bounds(items)
+          return [0, 0, 0, 0] if items.empty?
+
+          [-@radius - (@item_width / 2.0), -@radius - (@item_height / 2.0),
+           (@radius * 2) + @item_width, (@radius * 2) + @item_height]
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/row.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A Menu layout: buttons side by side rightwards from the menu's origin,
+      # all the same size, `spacing` pixels apart — a skill bar, a row of tabs.
+      # A UI::Stack on the horizontal axis, so the default UI::Stepping moves
+      # through it with `ui_left` and `ui_right`, with nothing else said.
+      #
+      #   UI::Menu.new(layout: UI::Row.new(item_width: 64, item_height: 64))
+      #
+      # It takes no `axis:` — a row that is not horizontal is a UI::Column.
+      class Row < Stack
+        def initialize(item_width:, item_height:, spacing: 8)
+          super(axis: :horizontal, item_width: item_width, item_height: item_height, spacing: spacing)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/shape_style.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A button background drawn from plain shapes — a rectangle or a disc, a
+      # fill per state, and an outline while focused or pressed — so a menu can
+      # be built and played before any art exists.
+      #
+      #   round = UI::ShapeStyle.new(shape: :disc)
+      #   quiet = UI::ShapeStyle.new(colors: UI::ShapeStyle::COLORS.merge(idle: nil), outline: nil)
+      #
+      # The fill is inset by `border` in every state, and the outline is the whole
+      # shape drawn under it, so a button does not change size as its state
+      # changes: focus only uncovers the ring the fill leaves. A disc is centred in
+      # the slot, as large as its shorter side.
+      #
+      # `nil` in `colors:` draws no fill in that state, and `outline: nil` draws no
+      # outline. Colours are coerced once, here, so `colors:` takes arrays and a
+      # draw allocates nothing; and a missing state is a `KeyError` here, rather
+      # than on the first frame a button happens to be disabled.
+      #
+      # Fill and outline are drawn at `z: 0` and `z: -1`. Shapes default to
+      # `z: 50`, which would cover the label or icon a button draws at `z: 1`.
+      #
+      # ## What reads on the fill is the style's to say
+      #
+      # `content:` is the colour a button draws its label or icon in over each
+      # state's fill, or `nil` to keep the button's own. The pressed fill is gold,
+      # and so is IconButton's pressed tint, so without it a pressed icon is gold
+      # on gold and vanishes; a light label nearly does. The style picks the fill,
+      # so it is the one place that can pick what goes on it. Defaults to dark
+      # while pressed and the button's own colour otherwise.
+      class ShapeStyle
+        SHAPES = %i[rect disc].freeze
+        OUTLINED = %i[focused pressed].freeze
+
+        COLORS = {
+          idle: Util::Color.new(52, 48, 62),
+          focused: Util::Color.new(72, 66, 88),
+          pressed: Util::Color.new(240, 200, 96),
+          disabled: Util::Color.new(40, 38, 46)
+        }.freeze
+        OUTLINE = Util::Color.new(240, 200, 96)
+        CONTENT = { idle: nil, focused: nil, pressed: Util::Color.new(46, 34, 24), disabled: nil }.freeze
+
+        FILL_Z = 0
+        OUTLINE_Z = -1
+
+        attr_reader :shape, :colors, :outline, :border, :content
+
+        def initialize(shape: :rect, colors: COLORS, outline: OUTLINE, border: 3, content: CONTENT)
+          unless SHAPES.include?(shape)
+            raise ArgumentError, "shape: must be one of #{SHAPES.inspect}, not #{shape.inspect}"
+          end
+
+          @shape = shape
+          @colors = Button::STATES.to_h { |state| [state, colors.fetch(state)&.then { Util::Color.coerce(it) }] }.freeze
+          @content = Button::STATES.to_h do |state|
+            [state, content.fetch(state)&.then { Util::Color.coerce(it) }]
+          end.freeze
+          @outline = outline&.then { Util::Color.coerce(it) }
+          @border = border
+        end
+
+        DEFAULT = new
+
+        # The colour a button draws its content in over this state's fill, or
+        # nil for the button's own. See "What reads on the fill" above.
+        def content_color(state) = @content.fetch(state)
+
+        def draw(renderer, state, width, height)
+          outlined = @outline && OUTLINED.include?(state)
+          fill = @colors.fetch(state)
+          if @shape == :disc
+            draw_disc(renderer, fill, outlined, width, height)
+          else
+            draw_rect(renderer, fill, outlined, width, height)
+          end
+        end
+
+        private
+
+        def draw_rect(renderer, fill, outlined, width, height)
+          renderer.rect(0, 0, width, height, z: OUTLINE_Z, color: @outline) if outlined
+          return unless fill
+
+          renderer.rect(@border, @border, width - (@border * 2), height - (@border * 2),
+                        z: FILL_Z, color: fill)
+        end
+
+        def draw_disc(renderer, fill, outlined, width, height)
+          cx = width / 2.0
+          cy = height / 2.0
+          radius = [width, height].min / 2.0
+          renderer.circle(cx, cy, radius, z: OUTLINE_Z, color: @outline) if outlined
+          renderer.circle(cx, cy, radius - @border, z: FILL_Z, color: fill) if fill
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/stack.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A Menu layout: buttons in a line from the menu's origin, all the same
+      # size, `spacing` pixels apart — downwards along the `:vertical` axis,
+      # rightwards along the `:horizontal` one. UI::Column and UI::Row are this
+      # with the axis fixed, and are what a game builds.
+      #
+      # A layout is anything that answers `arrange(buttons)` by setting each
+      # button's position and size, relative to the menu, `bounds(buttons)` with
+      # the rectangle that encloses them, and `axis` — the direction UI::Stepping
+      # moves focus along unless told otherwise. The Menu calls `arrange` and
+      # `bounds` every time a button is added, so a layout whose places depend on
+      # how many buttons there are — UI::Ring — re-spaces them all. It holds no
+      # state about any one menu, so one instance may serve several.
+      class Stack
+        AXES = %i[vertical horizontal].freeze
+
+        attr_reader :axis, :item_width, :item_height, :spacing
+
+        def initialize(axis:, item_width:, item_height:, spacing: 8)
+          raise ArgumentError, "axis: must be one of #{AXES.inspect}, not #{axis.inspect}" unless AXES.include?(axis)
+
+          @axis = axis
+          @item_width = item_width
+          @item_height = item_height
+          @spacing = spacing
+        end
+
+        def arrange(buttons)
+          vertical = @axis == :vertical
+          step = (vertical ? @item_height : @item_width) + @spacing
+          buttons.each_with_index do |button, index|
+            button.x = vertical ? 0 : index * step
+            button.y = vertical ? index * step : 0
+            button.width = @item_width
+            button.height = @item_height
+          end
+        end
+
+        # `[x, y, width, height]` of the buttons in their line, relative to the
+        # menu: all zero for no buttons, since no gap sits before the first.
+        def bounds(buttons)
+          count = buttons.size
+          return [0, 0, 0, 0] if count.zero?
+
+          if @axis == :vertical
+            [0, 0, @item_width, (count * @item_height) + ((count - 1) * @spacing)]
+          else
+            [0, 0, (count * @item_width) + ((count - 1) * @spacing), @item_height]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/stepping.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # Focus that moves one button at a time, along an axis: on a vertical one
+      # `ui_up` and `ui_down` step through the buttons in the order they were
+      # added and `ui_left` / `ui_right` go to the focused button; on a
+      # horizontal one the two pairs swap. Menu's default navigation.
+      #
+      #   UI::Menu.new(layout: UI::Column.new(item_width: 220, item_height: 44))  # up and down
+      #   UI::Menu.new(layout: UI::Row.new(item_width: 64, item_height: 64))      # left and right
+      #
+      # **The axis is the layout's** unless one is passed, so a UI::Row steps
+      # with left and right with nothing else said. `Stepping.new(axis:
+      # :horizontal)` overrides it — a UI::Ring stepped round with left and
+      # right, say. It is read once, when the menu is built.
+      #
+      # **Focus is never empty** while the menu has a button. It starts on the
+      # first enabled one, skips disabled ones as it moves, and wraps at the
+      # ends: a short list is quicker to get around when its ends join, and every
+      # console menu does it.
+      #
+      # **The other pair belongs to the focused button.** Only the button knows
+      # whether it has anything to change, so it is asked to `adjust` and a plain
+      # PanelButton answers nil. That is what makes UI::OptionButton work, and the
+      # reason an option row wants this navigation rather than UI::Pointing,
+      # where every direction is one to point in.
+      class Stepping < Navigation
+        ACTIONS = {
+          vertical: %i[ui_up ui_down ui_left ui_right].freeze,
+          horizontal: %i[ui_left ui_right ui_up ui_down].freeze
+        }.freeze
+
+        # The axis focus moves along: what was passed, or once the menu is
+        # built, its layout's. nil before then when none was passed.
+        attr_reader :axis
+
+        def initialize(axis: nil)
+          super()
+          @axis = axis
+        end
+
+        # Resolves the axis against the menu's layout. Raises ArgumentError for
+        # an axis outside UI::Stack::AXES.
+        def attach(menu)
+          super
+          @axis ||= menu.layout.axis
+          unless Stack::AXES.include?(@axis)
+            raise ArgumentError, "axis: must be one of #{Stack::AXES.inspect}, not #{@axis.inspect}"
+          end
+
+          @step_back, @step_on, @adjust_down, @adjust_up = ACTIONS.fetch(@axis)
+        end
+
+        # Moves focus by `delta`, skipping anything disabled, and wrapping. Does
+        # nothing at all if no button can take focus.
+        def step(delta)
+          buttons = menu.buttons
+          count = buttons.size
+          index = menu.focused_index || 0
+          tried = 0
+          while tried < count
+            index = (index + delta) % count
+            if buttons[index].enabled?
+              menu.focus(index)
+              return
+            end
+            tried += 1
+          end
+        end
+
+        def on_control(actions)
+          step(-1) if actions.pressed?(@step_back)
+          step(1) if actions.pressed?(@step_on)
+
+          current = menu.focused
+          return if current.nil?
+
+          current.adjust(-1) if actions.pressed?(@adjust_down)
+          current.adjust(1) if actions.pressed?(@adjust_up)
+        end
+
+        def on_buttons_changed
+          return if menu.focused&.enabled?
+
+          first = menu.buttons.index(&:enabled?)
+          menu.focus(first || 0)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/text_button.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A label centred on a style: the button to build a menu with before any
+      # art exists, and the base of every shipped button that draws a label.
+      #
+      #   menu.add(UI::TextButton.new(label: 'play')).on_activated { start }
+      #   menu.add(UI::TextButton.new(label: 'credits', style: UI::ShapeStyle.new(outline: nil)))
+      #   menu.add(UI::TextButton.new(label: 'quit', style: nil))
+      #
+      # With no `style:` it draws UI::ShapeStyle::DEFAULT, which needs nothing
+      # registered with the renderer. `style: nil` draws the label alone. The
+      # style draws at `z: 0` or below and the label at `z: 1`, so the label is
+      # always on top. Focus, pressing and activation are all UI::Button's.
+      #
+      # The label colours are coerced once, so they may be arrays and a draw
+      # still allocates nothing. A style answering `content_color(state)` —
+      # UI::ShapeStyle does — overrides them in any state it names, because what
+      # reads on a fill is the style's to say: a light label on a gold pressed
+      # fill would all but disappear. A subclass that draws more than a label —
+      # UI::OptionButton — overrides `draw_foreground`, and so keeps its style
+      # without having to remember to draw it.
+      class TextButton < Button
+        LABEL_COLOR = Util::Color.new(240, 236, 224)
+        DISABLED_LABEL_COLOR = Util::Color.new(120, 116, 128)
+
+        attr_reader :style, :label_color, :disabled_label_color
+
+        def initialize(label:, style: ShapeStyle::DEFAULT, label_color: LABEL_COLOR,
+                       disabled_label_color: DISABLED_LABEL_COLOR, **)
+          super(label: label, **)
+          @style = style
+          @style_names_content = style.respond_to?(:content_color)
+          @label_color = Util::Color.coerce(label_color)
+          @disabled_label_color = Util::Color.coerce(disabled_label_color)
+        end
+
+        def on_draw(renderer, _view)
+          @style&.draw(renderer, state, width, height)
+          draw_foreground(renderer)
+        end
+
+        private
+
+        def draw_foreground(renderer)
+          text = @label.to_s
+          renderer.text(text, centred_x(renderer, text), label_y(renderer), z: 1, color: current_label_color)
+        end
+
+        def current_label_color = style_content_color || (@enabled ? @label_color : @disabled_label_color)
+        def style_content_color = @style_names_content ? @style.content_color(state) : nil
+        def centred_x(renderer, text) = (width - renderer.text_width(text)) / 2
+        def label_y(renderer) = (height - renderer.text_height) / 2
+      end
+    end
+  end
+end