ricekit 0.2.0__py3-none-any.whl

ricekit/__init__.py

@@ -0,0 +1,36 @@
+"""ricekit — a developer's TUI suite for Textual.
+
+The themes, widgets, modals, icons, and design rules extracted from
+building ltui (https://github.com/Gheat1/ltui) — and now shared by its
+siblings jtui (Jira) and sctui (Shortcut): everything a fast,
+clean, rice-friendly terminal app needs, minus the app.
+
+    from ricekit import KitApp, palette, icons
+    from ricekit.widgets import NavList, Splitter, KitScroll, pop_in
+    from ricekit.modals import PickerModal, ThemeModal, HelpModal
+    from ricekit.storage import AppDirs
+
+See DESIGN.md for the philosophy and the sharp edges.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from ricekit import fx, icons
+from ricekit.app import KitApp
+from ricekit.palette import Palette, palette
+from ricekit.storage import AppDirs
+from ricekit.themes import KIT_THEMES, KIT_THEME_NAMES
+
+__all__ = [
+    "KitApp",
+    "Palette",
+    "palette",
+    "icons",
+    "fx",
+    "AppDirs",
+    "KIT_THEMES",
+    "KIT_THEME_NAMES",
+    "__version__",
+]

ricekit/app.py

@@ -0,0 +1,86 @@
+"""KitApp — the base App that wires the whole kit together."""
+
+from __future__ import annotations
+
+from textual.app import App
+from textual.color import Color
+
+from ricekit.modals import ThemeModal
+from ricekit.palette import palette
+from ricekit.themes import KIT_THEMES, KIT_THEME_NAMES
+
+
+class KitApp(App):
+    """App base with the kit's theme machinery.
+
+    Call `self.init_kit(theme=...)` from your `on_mount`. Then:
+
+    - the five kit themes are registered and one is active
+    - `App.ansi_color` flips automatically for ansi-background themes
+      (clear, system, ansi-dark, …) so the terminal background shows
+    - the shared `palette` swaps to ANSI colors under the `system` theme
+    - `action_change_theme` opens the live-preview ThemeModal (this also
+      replaces the command palette's built-in "Change theme" flow)
+    - `action_cycle_kit_theme` cycles the five kit themes (bind it to `t`)
+    - override `on_kit_theme_changed()` to re-render palette-dependent
+      content and persist the choice — check `self.kit_theme_previewing`
+      before persisting
+    """
+
+    kit_theme_previewing: bool = False
+
+    def get_css_variables(self) -> dict[str, str]:
+        # kit-* variables must exist even before our themes register (the
+        # stylesheet is parsed while the default textual theme is active),
+        # and when a non-kit builtin theme is active
+        variables = super().get_css_variables()
+        theme = next((t for t in KIT_THEMES if t.name == self.theme), KIT_THEMES[0])
+        for name, value in theme.variables.items():
+            variables.setdefault(name, value)
+        return variables
+
+    def init_kit(self, theme: str | None = None) -> None:
+        for t in KIT_THEMES:
+            self.register_theme(t)
+        self.theme_changed_signal.subscribe(self, self._kit_theme_changed)
+        if theme and theme in self.available_themes:
+            self.theme = theme
+        else:
+            self.theme = KIT_THEME_NAMES[0]
+        self._kit_apply()
+
+    def _kit_theme_is_ansi(self) -> bool:
+        theme = self.available_themes.get(self.theme)
+        if theme is None or theme.background is None:
+            return False
+        try:
+            return Color.parse(theme.background).ansi is not None
+        except Exception:
+            return False
+
+    def _kit_apply(self) -> None:
+        self.ansi_color = self._kit_theme_is_ansi()
+        palette.set_ansi(self.theme == "system")
+
+    def _kit_theme_changed(self, _theme) -> None:
+        self._kit_apply()
+        self.on_kit_theme_changed()
+
+    def on_kit_theme_changed(self) -> None:
+        """Override me: re-render Rich-text chrome, persist self.theme
+        (skip persisting while `self.kit_theme_previewing` is True)."""
+
+    def action_cycle_kit_theme(self) -> None:
+        idx = (
+            KIT_THEME_NAMES.index(self.theme)
+            if self.theme in KIT_THEME_NAMES
+            else -1
+        )
+        self.theme = KIT_THEME_NAMES[(idx + 1) % len(KIT_THEME_NAMES)]
+
+    def action_change_theme(self) -> None:
+        # overrides App.action_change_theme, so the command palette's
+        # "Change theme" command opens the live-preview picker too
+        if isinstance(self.screen, ThemeModal):
+            return
+        self.push_screen(ThemeModal())

ricekit/fx.py

@@ -0,0 +1,53 @@
+"""Text effects: the letter wave and the braille spinner.
+
+One shared ticker at ~8fps (0.12s) drives both; render only while a sweep
+or spin is active — idle frames should cost nothing.
+"""
+
+from __future__ import annotations
+
+from rich.markup import escape
+
+SPINNER_FRAMES = "\u280b\u2819\u2839\u2838\u283c\u2834\u2826\u2827\u2807\u280f"
+
+FX_TICK = 0.12  # seconds per animation frame
+FX_REST_TICKS = 26  # pause between wave sweeps (~3s)
+
+
+def wave_markup(s: str, pos: int, base: str, hi: str) -> str:
+    """One traveling letter, bolded + capitalized: gheatmc -> Gheatmc -> gHeatmc.
+
+    `pos` is the index of the highlighted letter (-1 or out of range = no
+    highlight). Advance pos on a timer; after the sweep, rest FX_REST_TICKS.
+    """
+    out = []
+    for i, ch in enumerate(s):
+        e = escape(ch)
+        if i == pos:
+            out.append(f"[bold {hi}]{e.upper()}[/]")
+        else:
+            out.append(f"[{base}]{e}[/]")
+    return "".join(out)
+
+
+class Wave:
+    """Sweep/rest state machine for wave_markup.
+
+    tick() returns True when a re-render is needed this frame.
+    """
+
+    def __init__(self, length: int, rest_ticks: int = FX_REST_TICKS) -> None:
+        self.length = length
+        self.rest_ticks = rest_ticks
+        self.pos = -1
+        self._rest = 0
+
+    def tick(self) -> bool:
+        if self._rest > 0:
+            self._rest -= 1
+            return False
+        self.pos += 1
+        if self.pos >= self.length:
+            self.pos = -1
+            self._rest = self.rest_ticks
+        return True

ricekit/gallery.py

@@ -0,0 +1,203 @@
+"""ricekit-gallery — a live demo of every piece of the kit.
+
+Also serves as the kit's integration test: if the gallery runs, the
+themes, palette, widgets, and modals all compose.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.text import Text
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Footer, OptionList, Static
+from textual.widgets.option_list import Option
+
+from ricekit import __version__, icons
+from ricekit.app import KitApp
+from ricekit.modals import HelpModal, PickerModal
+from ricekit.palette import palette
+from ricekit.storage import AppDirs
+from ricekit.widgets import KitScroll, NavList, Splitter, pop_in
+
+DIRS = AppDirs("ricekit-gallery")
+
+HELP_SECTIONS = [
+    ("navigate", [("j / k / arrows", "move"), ("enter", "show a demo"), ("esc", "close modal")]),
+    ("kit", [("t", "cycle the five kit themes"), ("ctrl+p", "palette → Change theme (live preview)"),
+             ("p", "open a PickerModal"), ("?", "this help")]),
+    ("layout", [("drag the divider", "resize the sidebar"), ("double-click it", "reset")]),
+    ("app", [("q", "quit")]),
+]
+
+DEMOS = ["palette", "icons", "state glyphs", "bars", "widgets", "philosophy"]
+
+
+class Gallery(KitApp):
+    TITLE = "ricekit gallery"
+
+    BINDINGS = [
+        Binding("t", "cycle_kit_theme", "theme"),
+        Binding("p", "picker_demo", "picker"),
+        Binding("question_mark", "help", "help"),
+        Binding("q", "quit", "quit"),
+    ]
+
+    CSS = """
+    #side {
+        width: 26;
+        margin: 0 0 0 1;
+        border: round $kit-border;
+        border-title-color: $kit-border-alt;
+    }
+    #side:focus-within { border: round $kit-border-focus; }
+    #stage {
+        width: 1fr;
+        margin: 0 1 0 0;
+        border: round $kit-border;
+        border-title-color: $kit-border-alt;
+    }
+    #stage-body { height: auto; padding: 1 2; }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Horizontal():
+            with Vertical(id="side"):
+                yield NavList(id="demos")
+            yield Splitter("#side", min_width=18, max_width=40,
+                           on_resized=self._layout_changed, id="split")
+            with Vertical(id="stage"):
+                with KitScroll(id="stage-scroll"):
+                    yield Static(id="stage-body")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        state = DIRS.load_state()
+        self.init_kit(theme=state.get("theme"))
+        side = self.query_one("#side")
+        side.border_title = f" {icons.STAR} ricekit {__version__} "
+        if w := state.get("side_w"):
+            side.styles.width = int(w)
+        self.query_one("#stage").border_title = " gallery "
+        demos = self.query_one("#demos", NavList)
+        demos.add_options([Option(Text(f" {d}"), id=d) for d in DEMOS])
+        demos.highlighted = 0
+        demos.focus()
+        self._show("palette")
+
+    def _layout_changed(self, target: str, width: int | None) -> None:
+        DIRS.save_state({"side_w": width})
+
+    def on_kit_theme_changed(self) -> None:
+        # re-render palette-dependent content; persist unless previewing
+        current = self.query_one("#demos", NavList).highlighted or 0
+        self._show(DEMOS[current])
+        if not self.kit_theme_previewing:
+            DIRS.save_state({"theme": self.theme})
+
+    # ── demo panes ────────────────────────────────────────────────────
+    @on(OptionList.OptionHighlighted, "#demos")
+    def _pick(self, event: OptionList.OptionHighlighted) -> None:
+        if event.option.id:
+            self._show(event.option.id)
+
+    def _show(self, demo: str) -> None:
+        body = Text()
+        if demo == "palette":
+            body.append("the swappable chrome palette\n\n", style=f"bold {palette.text}")
+            for role in ("text", "sub", "dim", "faint", "vfaint", "blue", "lav",
+                         "peach", "green", "red", "mauve", "yellow"):
+                value = getattr(palette, role)
+                body.append("  ██ ", style=value)
+                body.append(f"palette.{role}".ljust(18), style=palette.sub)
+                body.append(f"{value}\n", style=palette.dim)
+            body.append("\nswitch to the system theme (t) and watch these\n"
+                        "become your terminal's own ANSI colors.", style=palette.dim)
+        elif demo == "icons":
+            body.append("nerd-font icons (as \\uXXXX escapes)\n\n", style=f"bold {palette.text}")
+            names = [n for n in dir(icons) if n.isupper() and isinstance(getattr(icons, n), str)
+                     and n not in ("BULLET", "DOT_SEP")]
+            for name in sorted(names):
+                body.append(f"  {getattr(icons, name)}  ", style=palette.blue)
+                body.append(f"icons.{name}\n", style=palette.sub)
+        elif demo == "state glyphs":
+            body.append("workflow-state circles (plain unicode)\n\n", style=f"bold {palette.text}")
+            colors = {"triage": palette.mauve, "backlog": palette.dim,
+                      "unstarted": palette.sub, "started": palette.yellow,
+                      "review": palette.green, "completed": palette.blue,
+                      "canceled": palette.dim}
+            for state, glyph in icons.STATE_GLYPHS.items():
+                body.append(f"  {glyph}  ", style=colors.get(state, palette.sub))
+                body.append(f"{state}\n", style=palette.sub)
+        elif demo == "bars":
+            body.append("mini bar gauges\n\n", style=f"bold {palette.text}")
+            for label, lit in (("urgent", 3), ("high", 3), ("medium", 2), ("low", 1), ("none", 0)):
+                body.append("  ")
+                body.append_text(icons.bars(lit, palette.sub, palette.vfaint))
+                body.append(f"  {label}\n", style=palette.sub)
+        elif demo == "widgets":
+            body.append("what you're looking at\n\n", style=f"bold {palette.text}")
+            for name, desc in (
+                ("NavList", "vim keys, quiet cursor via $kit-cursor"),
+                ("Splitter", "drag the divider left of this pane; double-click resets"),
+                ("KitScroll", "focusable scrolling with j/k"),
+                ("PickerModal", "press p"),
+                ("ThemeModal", "ctrl+p → Change theme — previews as you scroll"),
+                ("HelpModal", "press ?"),
+                ("pop_in", "every modal fades in (~150ms)"),
+            ):
+                body.append(f"  {name.ljust(14)}", style=palette.blue)
+                body.append(f"{desc}\n", style=palette.sub)
+        elif demo == "philosophy":
+            body.append("the short version\n\n", style=f"bold {palette.text}")
+            for line in (
+                "cache first — render instantly, refresh in the background",
+                "rounded borders, titles in the border, one accent at a time",
+                "chrome colors are roles, data colors are data",
+                "keyboard first, everything clickable anyway",
+                "motion is a fade, 150ms, out_cubic — never more",
+                "themes restyle chrome only; clear + system respect the rice",
+            ):
+                body.append(f"  {icons.CHECK} ", style=palette.green)
+                body.append(f"{line}\n", style=palette.sub)
+            body.append("\nfull document: DESIGN.md", style=palette.dim)
+        self.query_one("#stage-body", Static).update(body)
+        self.query_one("#stage").border_subtitle = f" {demo} "
+
+    # ── modal demos ───────────────────────────────────────────────────
+    def action_picker_demo(self) -> None:
+        opts = []
+        for i, (glyph, label) in enumerate([
+            (icons.CHECK_CIRCLE, "ship it"),
+            (icons.CLOCK, "later"),
+            (icons.CROSS_CIRCLE, "never"),
+        ]):
+            row = Text()
+            row.append(f"{glyph} ", style=(palette.green, palette.yellow, palette.red)[i])
+            row.append(label, style=palette.text)
+            opts.append(Option(row, id=label))
+
+        def done(choice: str | None) -> None:
+            if choice:
+                self.notify(f"{icons.CHECK} you picked: {choice}")
+
+        self.push_screen(PickerModal("a PickerModal", opts), done)
+
+    def action_help(self) -> None:
+        if isinstance(self.screen, HelpModal):
+            return
+        self.push_screen(HelpModal(HELP_SECTIONS, title=f"{icons.KEYBOARD}  ricekit gallery"))
+
+
+def main() -> None:
+    if "--version" in sys.argv or "-v" in sys.argv:
+        print(f"ricekit {__version__}")
+        return
+    Gallery().run()
+
+
+if __name__ == "__main__":
+    main()

ricekit/icons.py

@@ -0,0 +1,70 @@
+"""Curated nerd-font icons, written as \\uXXXX escapes so source stays ASCII-safe.
+
+Never string-match raw private-use-area glyphs in tooling: PUA bytes do not
+round-trip reliably through editors and patch scripts. Escapes always do.
+"""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+
+# people & actions
+USER = "\uf007"
+USERS = "\uf0c0"
+CHECK = "\uf00c"
+CHECK_CIRCLE = "\uf058"
+CROSS_CIRCLE = "\uf057"
+PLUS = "\uf067"
+PENCIL = "\uf040"
+TRASH = "\uf1f8"
+
+# state & alerts
+WARN = "\uf071"
+BAN = "\uf05e"
+MINUS_CIRCLE = "\uf056"  # blocked
+EXCLAIM_CIRCLE = "\uf06a"  # blocking
+INFO_CIRCLE = "\uf05a"
+
+# objects
+TAG = "\uf02b"
+COMMENT = "\uf075"
+CLOCK = "\uf017"
+CALENDAR = "\uf073"
+BRANCH = "\uf126"
+LINK = "\uf0c1"
+EXTERNAL = "\uf08e"
+LIST = "\uf03a"
+STAR = "\uf005"
+KEYBOARD = "\uf11c"
+GEAR = "\uf013"
+PLUG = "\uf1e6"
+PAINTBRUSH = "\uf1fc"
+SEARCH = "\uf002"
+FILTER = "\uf0b0"
+REFRESH = "\uf021"
+LEVEL_UP = "\uf148"  # parent / up the tree
+SITEMAP = "\uf0e8"  # children / sub-items
+
+# workflow-state circles (plain unicode: consistent geometry, no font needed)
+STATE_GLYPHS = {
+    "triage": "\u25ce",     # circled ring
+    "backlog": "\u25cc",    # dotted circle
+    "unstarted": "\u25cb",  # empty circle
+    "started": "\u25d0",    # half circle
+    "review": "\u25d1",     # other half
+    "completed": "\u25cf",  # full circle
+    "canceled": "\u2298",   # slashed circle
+}
+
+BULLET = "\u25cf"
+DOT_SEP = " \u00b7 "
+
+
+def bars(lit: int, on: str, off: str, total: int = 3) -> Text:
+    """Mini bar gauge — e.g. priority levels, capacity, progress."""
+    chars = "\u2582\u2584\u2586\u2587\u2588"[:total]
+    t = Text()
+    for i, ch in enumerate(chars):
+        t.append(ch, style=on if i < lit else off)
+    return t

ricekit/modals.py

@@ -0,0 +1,184 @@
+"""Modal building blocks: picker, theme picker with live preview, help sheet."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.screen import ModalScreen
+from textual.widgets import OptionList, Static
+from textual.widgets.option_list import Option
+
+from ricekit.palette import palette
+from ricekit.widgets import NavList, pop_in
+
+
+class PickerModal(ModalScreen):
+    """Generic list picker: dismisses with the selected option's id (or None)."""
+
+    BINDINGS = [Binding("escape", "cancel", show=False)]
+
+    DEFAULT_CSS = """
+    PickerModal { align: center middle; background: $kit-overlay; }
+    PickerModal #kit-picker-box {
+        width: 44; height: auto; max-height: 80%;
+        background: $kit-modal-bg; border: round $kit-border-focus; padding: 1 1;
+    }
+    PickerModal #kit-picker-title { padding: 0 1 1 1; text-style: bold; }
+    PickerModal #kit-picker-list { height: auto; max-height: 16; }
+    """
+
+    def __init__(self, title: str, options: list[Option]) -> None:
+        super().__init__()
+        self._title = title
+        self._options = options
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="kit-picker-box"):
+            yield Static(Text(self._title, style=f"bold {palette.sub}"), id="kit-picker-title")
+            yield NavList(*self._options, id="kit-picker-list")
+
+    def on_mount(self) -> None:
+        pop_in(self.query_one("#kit-picker-box"))
+        self.query_one("#kit-picker-list").focus()
+
+    @on(OptionList.OptionSelected)
+    def _selected(self, event: OptionList.OptionSelected) -> None:
+        self.dismiss(event.option.id)
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)
+
+
+class ThemeModal(ModalScreen):
+    """Theme picker — highlighting a theme previews it live across the app.
+
+    While this modal is on screen, `KitApp.kit_theme_previewing` is True;
+    persistence hooks should check it (commit fires one final change with
+    the flag off).
+    """
+
+    BINDINGS = [Binding("escape", "cancel", show=False)]
+
+    DEFAULT_CSS = """
+    ThemeModal { align: center middle; background: $kit-overlay; }
+    ThemeModal #kit-theme-box {
+        width: 40; height: auto; max-height: 85%;
+        background: $kit-modal-bg; border: round $kit-border-focus; padding: 1 1;
+    }
+    ThemeModal #kit-theme-title { padding: 0 1 1 1; text-style: bold; }
+    ThemeModal #kit-theme-list { height: auto; max-height: 18; }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="kit-theme-box"):
+            yield Static(
+                Text("theme · scroll to preview", style=f"bold {palette.sub}"),
+                id="kit-theme-title",
+            )
+            yield NavList(id="kit-theme-list")
+
+    def _row(self, name: str, active: str) -> Option:
+        row = Text("  ")
+        on_it = name == active
+        row.append("● " if on_it else "○ ", style=palette.blue if on_it else palette.dim)
+        row.append(name, style=palette.text if on_it else palette.sub)
+        return Option(row, id=name)
+
+    def on_mount(self) -> None:
+        from ricekit.themes import KIT_THEME_NAMES
+
+        pop_in(self.query_one("#kit-theme-box"))
+        app = self.app
+        setattr(app, "kit_theme_previewing", True)
+        self._original = app.theme
+        ol = self.query_one("#kit-theme-list", NavList)
+        opts = [Option(Text(" kit", style=f"bold {palette.sub}"), disabled=True)]
+        index_of: dict[str, int] = {}
+        for name in KIT_THEME_NAMES:
+            index_of[name] = len(opts)
+            opts.append(self._row(name, self._original))
+        extra = sorted(n for n in app.available_themes if n not in KIT_THEME_NAMES)
+        if extra:
+            opts.append(Option(Text(" "), disabled=True))
+            opts.append(Option(Text(" textual", style=f"bold {palette.sub}"), disabled=True))
+            for name in extra:
+                index_of[name] = len(opts)
+                opts.append(self._row(name, self._original))
+        ol.add_options(opts)
+        ol.highlighted = index_of.get(self._original, 1)
+        ol.focus()
+
+    @on(OptionList.OptionHighlighted, "#kit-theme-list")
+    def _preview(self, event: OptionList.OptionHighlighted) -> None:
+        if event.option.id:
+            self.app.theme = event.option.id
+
+    @on(OptionList.OptionSelected, "#kit-theme-list")
+    def _select(self, event: OptionList.OptionSelected) -> None:
+        setattr(self.app, "kit_theme_previewing", False)
+        if event.option.id:
+            self.app.theme = event.option.id
+            # re-fire so persistence hooks see the final (non-preview) change
+            self.app.theme_changed_signal.publish(self.app.current_theme)
+        self.dismiss(True)
+
+    def action_cancel(self) -> None:
+        setattr(self.app, "kit_theme_previewing", False)
+        self.app.theme = self._original
+        self.dismiss(False)
+
+
+class HelpModal(ModalScreen):
+    """Keybinding cheatsheet. `sections` is [(title, [(key, description), …]), …]."""
+
+    BINDINGS = [
+        Binding("escape", "close_modal", show=False),
+        Binding("question_mark", "close_modal", show=False),
+        Binding("q", "close_modal", show=False),
+    ]
+
+    DEFAULT_CSS = """
+    HelpModal { align: center middle; background: $kit-overlay; }
+    HelpModal #kit-help-box {
+        width: 64; height: auto; max-height: 90%;
+        background: $kit-modal-bg; border: round $kit-border-focus; padding: 1 2;
+    }
+    HelpModal #kit-help-body { height: auto; max-height: 30; scrollbar-size-vertical: 1; }
+    """
+
+    def __init__(self, sections: list[tuple[str, list[tuple[str, str]]]], title: str = "keys") -> None:
+        super().__init__()
+        self._sections = sections
+        self._title = title
+
+    def compose(self) -> ComposeResult:
+        from ricekit.widgets import KitScroll
+
+        with Vertical(id="kit-help-box"):
+            yield Static(Text(self._title, style=f"bold {palette.sub}"))
+            with KitScroll(id="kit-help-body"):
+                yield Static(self._render_sections(), id="kit-help-text")
+
+    def _render_sections(self) -> Text:
+        # (not `_render` — that's a real internal method on every Widget)
+        body = Text()
+        key_w = max(
+            (len(k) for _, rows in self._sections for k, _ in rows), default=8
+        )
+        for i, (section, rows) in enumerate(self._sections):
+            if i:
+                body.append("\n")
+            body.append(f"\n {section}\n", style=f"bold {palette.dim}")
+            for key, desc in rows:
+                body.append(f"   {key.ljust(key_w + 2)}", style=palette.blue)
+                body.append(f"{desc}\n", style=palette.sub)
+        return body
+
+    def on_mount(self) -> None:
+        pop_in(self.query_one("#kit-help-box"))
+
+    def action_close_modal(self) -> None:
+        self.dismiss(None)

ricekit/palette.py

@@ -0,0 +1,66 @@
+"""The chrome palette — every UI color that isn't data.
+
+Reference `palette.<role>` at render time (never bake into import-time
+constants) so switching to the ANSI palette restyles a live app.
+"""
+
+from __future__ import annotations
+
+TRUECOLOR = {
+    "text": "#cdd6f4",
+    "sub": "#a6adc8",
+    "dim": "#6c7086",
+    "faint": "#45475a",
+    "vfaint": "#313244",
+    "blue": "#89b4fa",
+    "lav": "#b4befe",
+    "peach": "#fab387",
+    "green": "#a6e3a1",
+    "red": "#f38ba8",
+    "mauve": "#cba6f7",
+    "yellow": "#f9e2af",
+}
+
+# terminal-native equivalents, used by the `system` theme
+ANSI = {
+    "text": "default",
+    "sub": "white",
+    "dim": "bright_black",
+    "faint": "bright_black",
+    "vfaint": "bright_black",
+    "blue": "blue",
+    "lav": "bright_blue",
+    "peach": "yellow",
+    "green": "green",
+    "red": "red",
+    "mauve": "magenta",
+    "yellow": "yellow",
+}
+
+
+class Palette:
+    """Swappable color roles for text chrome (rich styles, not CSS)."""
+
+    text: str
+    sub: str
+    dim: str
+    faint: str
+    vfaint: str
+    blue: str
+    lav: str
+    peach: str
+    green: str
+    red: str
+    mauve: str
+    yellow: str
+
+    def __init__(self) -> None:
+        self.set_ansi(False)
+
+    def set_ansi(self, ansi: bool) -> None:
+        self.__dict__.update(ANSI if ansi else TRUECOLOR)
+        self.is_ansi = ansi
+
+
+palette = Palette()
+"""The shared palette instance. `from ricekit import palette`."""

ricekit/storage.py

@@ -0,0 +1,79 @@
+"""XDG-flavoured state, cache, and config for an app — the cache-first doctrine.
+
+Render from cache instantly, refresh in the background, and make every
+mutation update the cache immediately so what the user sees is always what
+they did.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from pathlib import Path
+
+
+class AppDirs:
+    """Per-app file locations plus tiny JSON state/cache helpers.
+
+    `save_state` MERGES a patch over what's on disk — callers never clobber
+    keys owned by other features (a lesson learned the hard way).
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.state_file = Path.home() / ".local/state" / name / "state.json"
+        self.cache_dir = Path.home() / ".cache" / name
+        self.config_file = Path.home() / ".config" / name / "config.toml"
+
+    # ── state ─────────────────────────────────────────────────────────
+    def load_state(self) -> dict:
+        try:
+            return json.loads(self.state_file.read_text())
+        except Exception:
+            return {}
+
+    def save_state(self, patch: dict) -> None:
+        try:
+            data = self.load_state()
+            data.update(patch)
+            self.state_file.parent.mkdir(parents=True, exist_ok=True)
+            self.state_file.write_text(json.dumps(data))
+        except Exception:
+            pass
+
+    # ── cache ─────────────────────────────────────────────────────────
+    def read_cache(self, name: str) -> dict | None:
+        try:
+            return json.loads((self.cache_dir / f"{name}.json").read_text())
+        except Exception:
+            return None
+
+    def write_cache(self, name: str, data: dict) -> None:
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+            (self.cache_dir / f"{name}.json").write_text(json.dumps(data))
+        except Exception:
+            pass
+
+    def clear_cache(self) -> int:
+        count = 0
+        try:
+            for f in self.cache_dir.glob("*.json"):
+                f.unlink()
+                count += 1
+        except Exception:
+            pass
+        return count
+
+    # ── config ────────────────────────────────────────────────────────
+    def load_config(self) -> dict:
+        try:
+            return tomllib.loads(self.config_file.read_text())
+        except Exception:
+            return {}
+
+    def save_secret(self, key: str, value: str) -> None:
+        """Write a single-value secret config (chmod 600)."""
+        self.config_file.parent.mkdir(parents=True, exist_ok=True)
+        self.config_file.write_text(f'{key} = "{value}"\n')
+        self.config_file.chmod(0o600)

ricekit/themes.py

@@ -0,0 +1,134 @@
+"""The five kit themes and their CSS variable contract.
+
+Every theme defines the same `kit-*` variables, plus explicit scrollbar and
+text-selection colors (Textual derives both from `primary` otherwise, which
+makes them identical murky blue). App stylesheets should use:
+
+    border: round $kit-border;            /* resting chrome            */
+    border: round $kit-border-focus;      /* focused panel             */
+    border: round $kit-border-alt;        /* secondary emphasis        */
+    background: $kit-modal-bg;            /* modal boxes               */
+    background: $kit-cursor;              /* list-cursor rows          */
+    background: $kit-overlay;             /* modal screen dim layer    */
+
+`clear` and `system` use ansi_default backgrounds: pair them with
+`KitApp`, which flips `App.ansi_color` so the terminal's own background
+(and palette, for `system`) shows through.
+"""
+
+from __future__ import annotations
+
+from textual.theme import Theme
+
+_ACCENTS = dict(success="#a6e3a1", warning="#f9e2af", error="#f38ba8", dark=True)
+
+KIT_THEMES: list[Theme] = [
+    Theme(
+        name="mocha",
+        primary="#89b4fa", secondary="#cba6f7", accent="#f5c2e7",
+        background="#1e1e2e", surface="#313244", panel="#181825",
+        foreground="#cdd6f4", **_ACCENTS,
+        variables={
+            "kit-border": "#45475a",
+            "kit-border-focus": "#89b4fa",
+            "kit-border-alt": "#b4befe",
+            "kit-modal-bg": "#181825",
+            "kit-cursor": "#3e4869",
+            "kit-overlay": "black 40%",
+            "scrollbar": "#313244",
+            "scrollbar-hover": "#45475a",
+            "scrollbar-active": "#585b70",
+            "scrollbar-background": "#181825",
+            "screen-selection-background": "#b4befe 35%",
+            "input-selection-background": "#b4befe 35%",
+        },
+    ),
+    Theme(
+        name="void",
+        primary="#89b4fa", secondary="#cba6f7", accent="#f5c2e7",
+        background="#000000", surface="#101018", panel="#070709",
+        foreground="#cdd6f4", **_ACCENTS,
+        variables={
+            "kit-border": "#26262e",
+            "kit-border-focus": "#89b4fa",
+            "kit-border-alt": "#b4befe",
+            "kit-modal-bg": "#0a0a10",
+            "kit-cursor": "#1e2a4a",
+            "kit-overlay": "black 40%",
+            "scrollbar": "#1e1e28",
+            "scrollbar-hover": "#2c2c38",
+            "scrollbar-active": "#3c3c4a",
+            "scrollbar-background": "#0a0a10",
+            "screen-selection-background": "#b4befe 30%",
+            "input-selection-background": "#b4befe 30%",
+        },
+    ),
+    Theme(
+        name="onyx",
+        primary="#9aa5b5", secondary="#7d8494", accent="#b8c0cc",
+        background="#0e0e11", surface="#1b1b20", panel="#131317",
+        foreground="#d4d6dd", **_ACCENTS,
+        variables={
+            "kit-border": "#33333c",
+            "kit-border-focus": "#9aa5b5",
+            "kit-border-alt": "#b8c0cc",
+            "kit-modal-bg": "#141419",
+            "kit-cursor": "#2b303b",
+            "kit-overlay": "black 40%",
+            "scrollbar": "#2a2a32",
+            "scrollbar-hover": "#3a3a44",
+            "scrollbar-active": "#4a4a56",
+            "scrollbar-background": "#131317",
+            "screen-selection-background": "#b8c0cc 30%",
+            "input-selection-background": "#b8c0cc 30%",
+        },
+    ),
+    # no background at all — the terminal's own background (and any
+    # blur/transparency it has) shows through; muted grey-slate chrome
+    Theme(
+        name="clear",
+        primary="#8a93a5", secondary="#6f7787", accent="#a9b1c0",
+        background="ansi_default", surface="ansi_default", panel="ansi_default",
+        foreground="#cdd6f4", **_ACCENTS,
+        variables={
+            "kit-border": "#3c3f4a",
+            "kit-border-focus": "#8a93a5",
+            "kit-border-alt": "#a9b1c0",
+            "kit-modal-bg": "#16161d",
+            "kit-cursor": "#282c38",
+            "kit-overlay": "transparent",
+            "scrollbar": "#3c3f4a",
+            "scrollbar-hover": "#4a4e5a",
+            "scrollbar-active": "#5a5f6d",
+            "scrollbar-background": "transparent",
+            "screen-selection-background": "#3f4655",
+            "input-selection-background": "#3f4655",
+        },
+    ),
+    # the terminal's own ANSI palette + no background: a custom kitty /
+    # alacritty / ghostty theme becomes the app theme
+    Theme(
+        name="system",
+        primary="ansi_blue", secondary="ansi_magenta", accent="ansi_cyan",
+        background="ansi_default", surface="ansi_default", panel="ansi_default",
+        foreground="ansi_default",
+        success="ansi_green", warning="ansi_yellow", error="ansi_red", dark=True,
+        variables={
+            "kit-border": "ansi_bright_black",
+            "kit-border-focus": "ansi_blue",
+            "kit-border-alt": "ansi_bright_blue",
+            "kit-modal-bg": "ansi_black",
+            "kit-cursor": "ansi_bright_black",
+            "kit-overlay": "transparent",
+            "scrollbar": "ansi_bright_black",
+            "scrollbar-hover": "ansi_bright_black",
+            "scrollbar-active": "ansi_blue",
+            "scrollbar-background": "ansi_default",
+            "screen-selection-background": "ansi_cyan",
+            "screen-selection-foreground": "ansi_black",
+            "input-selection-background": "ansi_cyan",
+        },
+    ),
+]
+
+KIT_THEME_NAMES = [t.name for t in KIT_THEMES]

ricekit/widgets.py

@@ -0,0 +1,132 @@
+"""Reusable widgets: vim-navigable lists, drag-to-resize splitters, motion."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.widgets import OptionList, Static
+
+
+def pop_in(widget, duration: float = 0.15) -> None:
+    """Fade a freshly mounted container into place.
+
+    Opacity only, on purpose: offset/slide animation isn't supported for
+    ScalarOffset in textual 8.x. 150ms out_cubic still reads as motion.
+    """
+    widget.styles.opacity = 0.0
+    widget.styles.animate("opacity", 1.0, duration=duration, easing="out_cubic")
+
+
+class NavList(OptionList):
+    """OptionList with vim navigation. Use disabled options as group headers —
+    keyboard navigation skips them automatically."""
+
+    BINDINGS = [
+        Binding("j", "cursor_down", show=False),
+        Binding("k", "cursor_up", show=False),
+        Binding("g", "first", show=False),
+        Binding("G", "last", show=False),
+    ]
+
+    DEFAULT_CSS = """
+    NavList {
+        background: transparent;
+        border: none;
+        padding: 0 1;
+        scrollbar-size-vertical: 1;
+    }
+    NavList:focus { background: transparent; border: none; }
+    NavList > .option-list--option-highlighted { background: $kit-cursor; }
+    NavList:focus > .option-list--option-highlighted { background: $kit-cursor; }
+    """
+
+
+class KitScroll(VerticalScroll):
+    """Focusable scroll container with vim keys (detail panes, docs, logs).
+
+    Anything you mount into this dynamically MUST have `height: auto` in CSS —
+    containers default to fr-height and make the scroll area under-measure
+    its content (scrolling then stops before the end).
+    """
+
+    can_focus = True
+    BINDINGS = [
+        Binding("j", "scroll_down", show=False),
+        Binding("k", "scroll_up", show=False),
+    ]
+
+    DEFAULT_CSS = """
+    KitScroll { scrollbar-size-vertical: 1; }
+    """
+
+
+class Splitter(Static):
+    """A full-height drag handle between panels.
+
+    Drag to resize `target` (a CSS selector); double-click resets to the
+    stylesheet default. Pass `on_resized(target_selector, width_or_None)`
+    to persist layout. `invert=True` for handles on the *left* edge of the
+    panel they resize (dragging left grows it).
+    """
+
+    can_focus = False
+    ALLOW_SELECT = False  # a drag here resizes; it must not start text selection
+
+    DEFAULT_CSS = """
+    Splitter { width: 1; height: 1fr; }
+    Splitter:hover, Splitter.dragging { background: $kit-border; }
+    """
+
+    def __init__(
+        self,
+        target: str,
+        invert: bool = False,
+        min_width: int = 16,
+        max_width: int = 100,
+        on_resized: Callable[[str, int | None], None] | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._target = target
+        self._invert = invert
+        self._min = min_width
+        self._max = max_width
+        self._on_resized = on_resized
+        self._drag_x: int | None = None
+        self._start_w: int = 0
+
+    def on_mouse_down(self, event) -> None:
+        # outer_size, not size: `size` is the content box, so bordered
+        # targets would drift by the border width every drag
+        self._drag_x = event.screen_x
+        self._start_w = self.app.query_one(self._target).outer_size.width
+        self.capture_mouse()
+        self.add_class("dragging")
+
+    def on_mouse_move(self, event) -> None:
+        if self._drag_x is None:
+            return
+        delta = event.screen_x - self._drag_x
+        if self._invert:
+            delta = -delta
+        cap = min(self._max, self.app.size.width - 50)
+        width = max(self._min, min(self._start_w + delta, cap))
+        self.app.query_one(self._target).styles.width = width
+
+    def on_mouse_up(self, event) -> None:
+        if self._drag_x is None:
+            return
+        self._drag_x = None
+        self.release_mouse()
+        self.remove_class("dragging")
+        if self._on_resized is not None:
+            width = self.app.query_one(self._target).outer_size.width
+            self._on_resized(self._target, width)
+
+    def on_click(self, event) -> None:
+        if getattr(event, "chain", 1) == 2:
+            self.app.query_one(self._target).styles.width = None
+            if self._on_resized is not None:
+                self._on_resized(self._target, None)

ricekit-0.2.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: ricekit
+Version: 0.2.0
+Summary: A developer's TUI suite for Textual — themes, widgets, modals, icons, and the design system behind ltui, jtui, and sctui
+Author: Gheat
+License: MIT
+Project-URL: Homepage, https://github.com/Gheat1/ricekit
+Project-URL: Repository, https://github.com/Gheat1/ricekit
+Project-URL: Issues, https://github.com/Gheat1/ricekit/issues
+Keywords: tui,textual,terminal,design-system,widgets,themes
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=1.0
+Dynamic: license-file
+
+<div align="center">
+
+# 🍚 ricekit
+
+**A developer's TUI suite for [Textual](https://github.com/Textualize/textual).**
+
+The themes, widgets, modals, icons, and design rules extracted from building
+[ltui](https://github.com/runpantheon/ltui) — and now powering its whole family
+(jtui, sctui, same repo) —
+everything a fast, clean, rice-friendly terminal app needs, minus the app.
+
+<img src="assets/gallery.png" alt="ricekit gallery" width="100%">
+
+</div>
+
+---
+
+## what's in the box
+
+| module | contents |
+| --- | --- |
+| `ricekit.themes` | five themes — `mocha`, OLED-black `void`, monochrome `onyx`, **`clear`** (transparent: your terminal's blur shows through), **`system`** (your terminal's own ANSI palette) — all sharing one `$kit-*` CSS variable contract, with the scrollbar/selection fixes baked in |
+| `ricekit.palette` | swappable chrome palette (`palette.text`, `.dim`, `.blue`, …) that flips to terminal ANSI colors under the `system` theme |
+| `ricekit.app` | `KitApp` — registers the themes, flips `ansi_color` for transparent themes, injects CSS variables, replaces the palette's theme command with a live-preview picker |
+| `ricekit.widgets` | `NavList` (vim keys, quiet cursor), `Splitter` (drag-to-resize with persistence hook, double-click reset), `KitScroll`, `pop_in` (the one sanctioned animation) |
+| `ricekit.modals` | `PickerModal` (generic chooser), `ThemeModal` (restyles the app live as you scroll), `HelpModal` (keybinding cheatsheet from plain data) |
+| `ricekit.icons` | curated nerd-font icons as `\uXXXX` escapes + unicode state glyphs (◌ ○ ◐ ◑ ● ⊘) + mini bar gauges |
+| `ricekit.fx` | text effects — the letter wave (`Wave` + `wave_markup`: **G**heat → g**H**eat → …) and braille spinner frames, driven by one cheap shared ticker |
+| `ricekit.storage` | `AppDirs` — XDG state/cache/config with merge-on-save state and chmod-600 secrets |
+| [`DESIGN.md`](DESIGN.md) | the philosophy: cache-first speed, shape language, color roles, motion rules — and the appendix of Textual sharp edges that each cost a day to find |
+
+## see it
+
+```sh
+uv tool install git+https://github.com/Gheat1/ricekit
+ricekit-gallery
+```
+
+The gallery demos the palette, icons, glyphs, widgets, and modals — cycle
+themes with `t`, live-preview every Textual theme with `ctrl+p`, drag the
+divider, press `?`.
+
+## use it
+
+```sh
+uv add git+https://github.com/Gheat1/ricekit   # or pip install git+…
+```
+
+```python
+from textual.binding import Binding
+from textual.widgets import Footer
+
+from ricekit import KitApp, icons, palette
+from ricekit.storage import AppDirs
+from ricekit.widgets import NavList
+
+DIRS = AppDirs("myapp")
+
+class MyApp(KitApp):
+    BINDINGS = [Binding("t", "cycle_kit_theme", "theme")]
+    CSS = """
+    NavList { border: round $kit-border; }
+    NavList:focus { border: round $kit-border-focus; }
+    """
+
+    def compose(self):
+        yield NavList(id="items")
+        yield Footer()
+
+    def on_mount(self):
+        self.init_kit(theme=DIRS.load_state().get("theme"))
+
+    def on_kit_theme_changed(self):
+        if not self.kit_theme_previewing:
+            DIRS.save_state({"theme": self.theme})
+```
+
+That's a themed, transparent-capable, live-previewing app in ~25 lines.
+Read [`DESIGN.md`](DESIGN.md) before building anything serious — especially
+the sharp-edges table.
+
+## the suite
+
+- [**the tracker TUI suite**](https://github.com/runpantheon/ltui) — ltui (Linear), jtui (Jira), sctui (Shortcut); where all of this came from, now backed by Pantheon
+- [**NaviTui**](https://github.com/Gheat1/NaviTui) — an animated terminal player for Navidrome, cover art and all
+- yours next?
+
+## license
+
+[MIT](LICENSE) — made by [@Gheat1](https://github.com/Gheat1)

ricekit-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ricekit/__init__.py,sha256=w98nVE7BAgP17vLTmPt7S98epTI0afxVvuwEro00z5c,1008
+ricekit/app.py,sha256=G-KNgIwUmJFu-DwU26ObEXrXLqwpBryTHKMYtuySot8,3294
+ricekit/fx.py,sha256=4luWwdbJhljgSCNrPHAJpVjDiBbkjBP-aAyWomXxy9k,1548
+ricekit/gallery.py,sha256=PzoyHALqJD_X9U2-DK084qmKSqTTQ8df4Ht7K-VIDNU,8856
+ricekit/icons.py,sha256=cbuWe7bEkHgmCzK8GFiGyA_aEuVU-uhSF6c0GjTMgiQ,1742
+ricekit/modals.py,sha256=JU8IB1u8LX9BP8Vkjp8tLhiXBcdsZsxPnukMWVqQLt8,6975
+ricekit/palette.py,sha256=YeT8u_88afef1YSj2jcpmZxWpdnlGyQj2tKtFAU8GDg,1431
+ricekit/storage.py,sha256=680byZSzjK0bp2P-TBah8v8GvP8L_x5FzFzjpRRe_AE,2995
+ricekit/themes.py,sha256=uXAmG4x5HfbF6B7EKMKLWiTWu66Q41zEF7HIav3xKmc,5452
+ricekit/widgets.py,sha256=v9omCfHo8DWltJp2EFwRqgzW5bNsfFH9JqcO8mQjZII,4380
+ricekit-0.2.0.dist-info/licenses/LICENSE,sha256=IDB7sG2R5p1TBTo0JAytpj4ghJmItQMZflxsdraGSIk,1062
+ricekit-0.2.0.dist-info/METADATA,sha256=Ed0OB1ZhWGaYAFLhRIOtH3w6cpnTmyCkkFbvIA75nUA,4581
+ricekit-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ricekit-0.2.0.dist-info/entry_points.txt,sha256=lNtmENuPDSt_MfEZjJ2kNJjxSxXFzhqlVGAl38ymsu0,57
+ricekit-0.2.0.dist-info/top_level.txt,sha256=9AtVU14JFZEKl9nLyrCZpw4p9hOaFN7e7FmERFZyBQo,8
+ricekit-0.2.0.dist-info/RECORD,,

ricekit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ricekit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ricekit-gallery = ricekit.gallery:main

ricekit-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gheat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ricekit-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ricekit