Selkie.git | docs/api/ | Selkie--Widget--TabBar.md
NAME
====
Selkie::Widget::TabBar - Horizontal tab strip integrated with ScreenManager
SYNOPSIS
========
```raku
use Selkie::Widget::TabBar;
use Selkie::Sizing;
my $tabs = Selkie::Widget::TabBar.new(sizing => Sizing.fixed(1));
$tabs.add-tab(name => 'tasks', label => 'Tasks');
$tabs.add-tab(name => 'notes', label => 'Notes');
$tabs.add-tab(name => 'stats', label => 'Stats');
# Tap to react to user selection:
$tabs.on-tab-selected.tap: -> Str $name {
$app.switch-screen($name);
};
```
DESCRIPTION
===========
A one-line horizontal strip of named tabs. The active tab is highlighted with the theme's `text-highlight` slot; others render in the default `text` slot. Focusable — Left/Right arrows move the active tab, `Enter` fires `on-tab-selected` (which you typically tap to call `$app.switch-screen`).
Tabs are identified by an opaque `name` string and displayed as a `label`. The name is what's emitted on `on-tab-selected` — choose something that matches your registered screen names for a zero-effort integration with `Selkie::ScreenManager`.
`TabBar` also has convenient integration with `ScreenManager`: call `sync-to-app($app)` to make the active tab reflect `$app.screen-manager.active-screen` automatically via a store subscription.
Tabs can carry a **badge** — an unread count, a pending-item tally, anything short — drawn inside the tab after its label. The active-tab decoration and the focus indicator are both configurable (`TabActiveStyle` / `TabFocusIndicator`, exported by this module; `use Selkie` does not re-export them). All defaults are byte-for-byte what TabBar has always drawn.
BADGES
======
A badge is any value; it's stored raw and stringified at render time by `badge-formatter`, so a store subscription can hand over `Int` counts without formatting them first:
```raku
$tabs.add-tab(name => 'inbox', label => 'Inbox', badge => 4);
$tabs.set-badge('inbox', 12); # → "[ Inbox 12 ]"
$tabs.set-badge('inbox', Nil); # → "[ Inbox ]" (same as clear-badge)
$tabs.clear-badge('inbox');
say $tabs.badge('inbox'); # Nil — the raw value, not the drawn text
```
The stock formatter is `.Str`, except `Int`s above 99, which clamp to `'99+'` — an unbounded count would widen its tab and shove every tab to its right along with it. Override it for a different policy; returning the empty string draws no badge at all, which is the idiom for suppressing zeroes:
```raku
$tabs.set-badge-formatter(-> $v { $v ~~ Int && $v == 0 ?? '' !! $v.Str });
$tabs.set-badge-prefix(' · '); # separator between label and badge
# Wrapping the stock policy rather than replacing it:
my &stock = Selkie::Widget::TabBar.default-badge-formatter;
$tabs.set-badge-formatter(-> $v { $v ~~ Int && $v == 0 ?? '' !! &stock($v) });
```
Badges count towards the tab's width, so mouse hit-testing follows them automatically — see [LAYOUT INTROSPECTION](LAYOUT INTROSPECTION).
ACTIVE-TAB STYLES
=================
* **`TabBrackets`** — the default. The active tab is wrapped in `[ ]`: `[ Inbox ]`.
* **`TabUnderline`** — no brackets; the active tab is underlined instead (padding included, so the rule runs the full width of the tab).
* **`TabPill`** — no brackets; the active tab is filled with the theme's `tab-active` background.
Every style draws the same number of columns for the same tab — `"[ L ]"` and `" L "` are both `L.chars + 4` — so switching styles never shifts the strip.
They differ in how an **unfocused** bar marks its active tab. Brackets and underline recede to the `tab-inactive` colours (the glyph-level decoration still says which tab is current), while a pill stays lit, because its fill is the only marker it has. That's deliberate: a pill bar leans on the focus indicator, not colour, to say whether it's being driven.
```raku
my $tabs = Selkie::Widget::TabBar.new(
sizing => Sizing.fixed(1),
active-style => TabPill,
focus-indicator => FocusColor,
);
$tabs.set-active-style(TabUnderline); # or change it later; marks dirty
```
FOCUS INDICATION
================
`FocusPrefix` (the default) draws `'▶ '` before the first tab while the bar is focused and two blank cells while it isn't — the same width either way, so nothing moves when focus arrives.
`FocusColor` drops the prefix entirely (the strip starts at column 0) and merges the theme's `tab-focus-accent` slot onto the active tab instead. That slot defaults to `border-focused`, so a bar switched to `FocusColor` picks up the same accent the rest of your chrome uses for focus; give the slot its own colour for something distinct.
The accent is merged, so whatever it sets wins. That matters with `TabPill`: an accent carrying a `bg` (`border-focused` does) replaces the pill's fill rather than tinting it, and a focused pill ends up flat-on-base while an unfocused one stays filled. If you want a focused pill that's filled *in* the accent, give `tab-focus-accent` a background of its own:
```raku
tab-focus-accent => Selkie::Style.new(fg => 0x1A1A2E, bg => 0xBB99FF, bold => True),
```
LAYOUT INTROSPECTION
====================
`render` and mouse hit-testing share one width formula, exposed so you can share it too: `tab-display($i)` is the exact string tab `$i` draws, `focus-prefix` is the offset before the first tab, and `tab-index-at-col($col)` maps a local column back to a tab index (`-1` for the prefix or past the last tab).
```raku
my $width = $tabs.focus-prefix.chars
+ (^$tabs.tab-names.elems).map({ $tabs.tab-display($_).chars }).sum;
```
EXAMPLES
========
Wiring to ScreenManager
-----------------------
The canonical pattern: one tab per screen, selection dispatches a screen switch, and the bar keeps itself in sync if the screen changes from elsewhere:
```raku
my $tabs = Selkie::Widget::TabBar.new(sizing => Sizing.fixed(1));
$tabs.add-tab(name => 'inbox', label => 'Inbox');
$tabs.add-tab(name => 'sent', label => 'Sent');
$tabs.add-tab(name => 'drafts', label => 'Drafts');
$tabs.on-tab-selected.tap: -> Str $name {
$app.switch-screen($name);
};
# Keep the bar's active tab in sync with whatever's actually showing
$tabs.sync-to-app($app);
```
Without ScreenManager
---------------------
Tabs don't have to drive screen switches — you can use them as a lightweight "mode" selector for a single screen's content:
```raku
my $tabs = Selkie::Widget::TabBar.new(sizing => Sizing.fixed(1));
$tabs.add-tab(name => 'recent', label => 'Recent');
$tabs.add-tab(name => 'saved', label => 'Saved');
$tabs.add-tab(name => 'all', label => 'All');
$tabs.on-tab-selected.tap: -> Str $name {
$app.store.dispatch('view/mode-changed', mode => $name);
};
```
Count badges from the store
---------------------------
Badges are usually a projection of application state. Recompute them in one callback and let the formatter decide what's worth drawing:
```raku
$app.store.subscribe-with-callback(
'tab-counts',
-> $s { $s.get-in('counts') // {} },
-> %counts {
$tabs.set-badge($_, %counts{$_} // Nil) for $tabs.tab-names;
},
$tabs,
);
# Suppress zeroes rather than drawing "Inbox 0":
$tabs.set-badge-formatter(-> $v { $v ~~ Int && $v == 0 ?? '' !! $v.Str });
```
`set-badge` is a no-op when the value hasn't changed, so a subscription that fires on every store tick doesn't cause a repaint per tick.
SEE ALSO
========
* [Selkie::ScreenManager](Selkie--ScreenManager.md) — the multi-screen registry TabBar typically drives
* [Selkie::App](Selkie--App.md) — screen-scoped keybinds complement per-tab views
* [Selkie::Theme](Selkie--Theme.md) — the `tab-active`, `tab-inactive` and `tab-focus-accent` slots
How the active tab is decorated. `TabBrackets` is the historical behaviour and the default: the active tab is wrapped in `[ ]`. `TabUnderline` drops the brackets and underlines the active tab instead. `TabPill` drops them too and leaves the tab filled with the theme's `tab-active` background — the "pill" look. All three render the same number of columns for the same tab, so switching styles never shifts the strip's layout: `"[ L ]"` and `" L "` are both `L.chars + 4`.
How a focused bar announces that it has the keyboard. `FocusPrefix` is the historical behaviour and the default: a `▶ ` chevron in front of the strip (blank padding when unfocused, so the tabs never move). `FocusColor` drops the prefix entirely — the strip starts at column 0 — and instead merges the theme's `tab-focus-accent` slot onto the active tab while the bar is focused.
### has TabActiveStyle $.active-style
How the active tab is decorated. Defaults to `TabBrackets`, which is byte-for-byte what TabBar has always drawn. Change it after construction with `set-active-style`.
### has TabFocusIndicator $.focus-indicator
How the bar shows that it holds focus. Defaults to `FocusPrefix`, the historical `▶ ` chevron. Change it after construction with `set-focus-indicator`.
### has Str $.badge-prefix
Separator inserted between a tab's label and its badge. Defaults to a single space, giving `[ Inbox 4 ]`. Set it to something like `' · '` for a heavier separator — it counts towards the tab's width, so hit-testing follows automatically.
### has Callable &.badge-formatter
Callable turning a badge value into the text drawn inside the tab. Receives the raw value passed to `add-tab`/`set-badge` and returns a `Str`; return the empty string to draw no badge at all. Defaults to `TabBar.default-badge-formatter`.
### method default-badge-formatter
```raku
method default-badge-formatter() returns Callable:D
```
The stock badge formatter: `.Str` for everything, except `Int`s above 99, which become `'99+'`. Handy to restore after a custom formatter, or to wrap one around it — see the BADGES section.
### method tab-display
```raku
method tab-display(
Int $i where { ... }
) returns Str
```
The exact string tab `$i` renders as — brackets or padding, label, separator and badge. Empty string for an out-of-range index. Public so callers can measure the strip (`sum` the displays plus `focus-prefix.chars` for its total width) and so tests can assert that hit-testing and rendering agree.
### method focus-prefix
```raku
method focus-prefix() returns Str
```
The leading offset drawn before the first tab: `'▶ '` / `' '` under `FocusPrefix`, `''` under `FocusColor`.
### method tab-index-at-col
```raku
method tab-index-at-col(
Int $col
) returns Int
```
The tab index covering local column `$col`, or `-1` for the focus prefix, a negative column, or anything past the last tab. This is the same lookup the widget's own click handler uses — reach for it when embedding a TabBar in a region you hit-test yourself.
### method add-tab
```raku
method add-tab(
Str:D :$name!,
Str:D :$label!,
:$badge
) returns Mu
```
Register a tab. `name` is the identifier (usually matches a screen name); `label` is what's shown to the user. Tabs render in the order they're added. Pass `:badge` to attach a count (or any value the formatter understands) drawn inside the tab after the label.
### method set-badge
```raku
method set-badge(
Str:D $name,
$badge
) returns Nil
```
Attach a badge to the named tab, or clear it by passing `Nil`. No-op for an unknown name. The value is stored raw and run through `badge-formatter` at render time, so a store subscription can push `Int` counts straight in.
### method clear-badge
```raku
method clear-badge(
Str:D $name
) returns Nil
```
Remove the named tab's badge. No-op for an unknown name.
### method badge
```raku
method badge(
Str:D $name
) returns Mu
```
The raw (unformatted) badge value attached to the named tab, or `Nil` if it has none — or the name isn't registered.
### method set-active-style
```raku
method set-active-style(
TabActiveStyle:D $style
) returns Nil
```
Switch the active-tab decoration. Marks dirty when it changes.
### method set-focus-indicator
```raku
method set-focus-indicator(
TabFocusIndicator:D $indicator
) returns Nil
```
Switch the focus indicator. Marks dirty when it changes.
### method set-badge-prefix
```raku
method set-badge-prefix(
Str:D $prefix
) returns Nil
```
Set the label/badge separator. Marks dirty when it changes.
### method set-badge-formatter
```raku
method set-badge-formatter(
&formatter
) returns Nil
```
Replace the badge formatter. Pass an undefined `Callable` to fall back to `default-badge-formatter`.
### method remove-tab
```raku
method remove-tab(
Str:D $name
) returns Mu
```
Remove a tab by name. If the removed tab was active, activation falls to the tab that was to its left (or index 0).
### method clear-tabs
```raku
method clear-tabs() returns Mu
```
Remove all tabs.
### method active-name
```raku
method active-name() returns Str
```
Tab name of the currently active tab, or `Nil` if the bar is empty.
### method active-index
```raku
method active-index() returns UInt
```
Index of the active tab.
### method tab-names
```raku
method tab-names() returns List
```
Tab names in order.
### method select-by-name
```raku
method select-by-name(
Str:D $name
) returns Mu
```
Activate the tab with this name. No-op if the name isn't registered or already active. Emits `on-tab-selected`.
### method select-index
```raku
method select-index(
Int $idx where { ... }
) returns Mu
```
Activate the tab at this index. No-op if already active or out of range.
### method set-active-name-silent
```raku
method set-active-name-silent(
Str:D $name
) returns Mu
```
Silently set the active index (no `on-tab-selected` emit). Use from a store subscription that syncs the bar to external state — prevents feedback loops.
### method on-tab-selected
```raku
method on-tab-selected() returns Supply
```
Supply emitting the `name` of the newly-active tab whenever the user changes it (or a programmatic `select-by-name` fires).
### method sync-to-app
```raku
method sync-to-app(
$app
) returns Mu
```
Install a store subscription that keeps this TabBar's active tab synced to `$app.screen-manager.active-screen`. Makes the bar self-consistent: if you call `$app.switch-screen(...)` elsewhere, the bar's highlight follows along.
### method set-focused
```raku
method set-focused(
Bool $f
) returns Mu
```
Set the bar's focus state. Called by `Selkie::App`'s focus dispatcher; apps don't usually call this directly. Under `FocusPrefix` the `▶` chevron appears; under `FocusColor` the active tab takes the theme's `tab-focus-accent`.
### method is-focused
```raku
method is-focused() returns Bool
```
Whether the bar currently has keyboard focus.