cs-ui 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cs_ui-0.1.0/PKG-INFO +462 -0
- cs_ui-0.1.0/README.md +442 -0
- cs_ui-0.1.0/pyproject.toml +48 -0
- cs_ui-0.1.0/setup.cfg +4 -0
- cs_ui-0.1.0/src/cs_ui.egg-info/PKG-INFO +462 -0
- cs_ui-0.1.0/src/cs_ui.egg-info/SOURCES.txt +107 -0
- cs_ui-0.1.0/src/cs_ui.egg-info/dependency_links.txt +1 -0
- cs_ui-0.1.0/src/cs_ui.egg-info/entry_points.txt +3 -0
- cs_ui-0.1.0/src/cs_ui.egg-info/requires.txt +9 -0
- cs_ui-0.1.0/src/cs_ui.egg-info/top_level.txt +2 -0
- cs_ui-0.1.0/src/ui/__init__.py +30 -0
- cs_ui-0.1.0/src/ui/app.py +249 -0
- cs_ui-0.1.0/src/ui/chart/__init__.py +12 -0
- cs_ui-0.1.0/src/ui/chart/_data.py +347 -0
- cs_ui-0.1.0/src/ui/chart/bar_chart.py +269 -0
- cs_ui-0.1.0/src/ui/chart/line_chart.py +395 -0
- cs_ui-0.1.0/src/ui/chart/rea_chart.py +244 -0
- cs_ui-0.1.0/src/ui/chart/scatter_chart.py +202 -0
- cs_ui-0.1.0/src/ui/cli.py +2 -0
- cs_ui-0.1.0/src/ui/components/icon_button.py +25 -0
- cs_ui-0.1.0/src/ui/core/__init__.py +104 -0
- cs_ui-0.1.0/src/ui/core/config.py +42 -0
- cs_ui-0.1.0/src/ui/core/constants.py +74 -0
- cs_ui-0.1.0/src/ui/core/float_layer.py +185 -0
- cs_ui-0.1.0/src/ui/core/language.py +0 -0
- cs_ui-0.1.0/src/ui/core/logger.py +163 -0
- cs_ui-0.1.0/src/ui/core/snackbar.py +70 -0
- cs_ui-0.1.0/src/ui/core/styles.py +150 -0
- cs_ui-0.1.0/src/ui/core/theme.py +383 -0
- cs_ui-0.1.0/src/ui/core/tokens.py +278 -0
- cs_ui-0.1.0/src/ui/display/__init__.py +48 -0
- cs_ui-0.1.0/src/ui/display/echarts.py +1 -0
- cs_ui-0.1.0/src/ui/display/image.py +78 -0
- cs_ui-0.1.0/src/ui/display/image_gridview.py +234 -0
- cs_ui-0.1.0/src/ui/display/list_tile.py +6 -0
- cs_ui-0.1.0/src/ui/display/log_container.py +91 -0
- cs_ui-0.1.0/src/ui/display/media/__init__.py +15 -0
- cs_ui-0.1.0/src/ui/display/media/audio.py +167 -0
- cs_ui-0.1.0/src/ui/display/media/pdf.py +237 -0
- cs_ui-0.1.0/src/ui/display/media/video.py +106 -0
- cs_ui-0.1.0/src/ui/display/text.py +120 -0
- cs_ui-0.1.0/src/ui/feedback/__init__.py +27 -0
- cs_ui-0.1.0/src/ui/feedback/alert_dialog.py +213 -0
- cs_ui-0.1.0/src/ui/feedback/loading.py +15 -0
- cs_ui-0.1.0/src/ui/feedback/message.py +120 -0
- cs_ui-0.1.0/src/ui/feedback/progress_bar.py +18 -0
- cs_ui-0.1.0/src/ui/feedback/toast.py +230 -0
- cs_ui-0.1.0/src/ui/ft_init.py +538 -0
- cs_ui-0.1.0/src/ui/input/__init__.py +44 -0
- cs_ui-0.1.0/src/ui/input/button.py +235 -0
- cs_ui-0.1.0/src/ui/input/calendar_panel.py +407 -0
- cs_ui-0.1.0/src/ui/input/checkbox.py +184 -0
- cs_ui-0.1.0/src/ui/input/chip.py +168 -0
- cs_ui-0.1.0/src/ui/input/color_picker.py +1474 -0
- cs_ui-0.1.0/src/ui/input/date_input.py +460 -0
- cs_ui-0.1.0/src/ui/input/datetime_input.py +821 -0
- cs_ui-0.1.0/src/ui/input/file_picker.py +213 -0
- cs_ui-0.1.0/src/ui/input/image_picker.py +58 -0
- cs_ui-0.1.0/src/ui/input/input.py +299 -0
- cs_ui-0.1.0/src/ui/input/multi_select.py +633 -0
- cs_ui-0.1.0/src/ui/input/panel_field.py +363 -0
- cs_ui-0.1.0/src/ui/input/radio.py +98 -0
- cs_ui-0.1.0/src/ui/input/rating.py +89 -0
- cs_ui-0.1.0/src/ui/input/search_bar.py +25 -0
- cs_ui-0.1.0/src/ui/input/segmented_button.py +60 -0
- cs_ui-0.1.0/src/ui/input/select_box.py +100 -0
- cs_ui-0.1.0/src/ui/input/slider.py +189 -0
- cs_ui-0.1.0/src/ui/input/switch.py +75 -0
- cs_ui-0.1.0/src/ui/layout/__init__.py +39 -0
- cs_ui-0.1.0/src/ui/layout/card.py +58 -0
- cs_ui-0.1.0/src/ui/layout/column.py +20 -0
- cs_ui-0.1.0/src/ui/layout/container.py +29 -0
- cs_ui-0.1.0/src/ui/layout/divider.py +16 -0
- cs_ui-0.1.0/src/ui/layout/expander.py +572 -0
- cs_ui-0.1.0/src/ui/layout/grid_view.py +8 -0
- cs_ui-0.1.0/src/ui/layout/list_view.py +8 -0
- cs_ui-0.1.0/src/ui/layout/page.py +166 -0
- cs_ui-0.1.0/src/ui/layout/row.py +11 -0
- cs_ui-0.1.0/src/ui/layout/stack.py +11 -0
- cs_ui-0.1.0/src/ui/layout/table.py +270 -0
- cs_ui-0.1.0/src/ui/layout/tabs.py +68 -0
- cs_ui-0.1.0/src/ui/layout/time_line.py +729 -0
- cs_ui-0.1.0/src/ui/layout/view.py +11 -0
- cs_ui-0.1.0/src/ui/navigation/__init__.py +7 -0
- cs_ui-0.1.0/src/ui/navigation/app_bar.py +6 -0
- cs_ui-0.1.0/src/ui/navigation/bread_crumb.py +177 -0
- cs_ui-0.1.0/src/ui/navigation/paging.py +300 -0
- cs_ui-0.1.0/src/ui/theme.py +1 -0
- cs_ui-0.1.0/src/ui/utils/__init__.py +4 -0
- cs_ui-0.1.0/src/ui/utils/code_editor.py +7 -0
- cs_ui-0.1.0/src/ui/utils/code_view.py +18 -0
- cs_ui-0.1.0/src/ui/utils/componts.py +40 -0
- cs_ui-0.1.0/src/ui_mcp/__about__.py +7 -0
- cs_ui-0.1.0/src/ui_mcp/__init__.py +27 -0
- cs_ui-0.1.0/src/ui_mcp/__main__.py +6 -0
- cs_ui-0.1.0/src/ui_mcp/aliases.py +152 -0
- cs_ui-0.1.0/src/ui_mcp/build.py +112 -0
- cs_ui-0.1.0/src/ui_mcp/cli.py +153 -0
- cs_ui-0.1.0/src/ui_mcp/data/api.json +1 -0
- cs_ui-0.1.0/src/ui_mcp/data/docs.json +1 -0
- cs_ui-0.1.0/src/ui_mcp/data/examples.json +1 -0
- cs_ui-0.1.0/src/ui_mcp/docs.py +230 -0
- cs_ui-0.1.0/src/ui_mcp/examples.py +339 -0
- cs_ui-0.1.0/src/ui_mcp/guidelines.py +288 -0
- cs_ui-0.1.0/src/ui_mcp/introspect.py +745 -0
- cs_ui-0.1.0/src/ui_mcp/paths.py +69 -0
- cs_ui-0.1.0/src/ui_mcp/search.py +79 -0
- cs_ui-0.1.0/src/ui_mcp/server.py +471 -0
- cs_ui-0.1.0/src/ui_mcp/store.py +557 -0
cs_ui-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,462 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cs_ui
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python UI framework inspired by Flet
|
|
5
|
+
Author-email: Shawn Chen <cs@cstos.com>
|
|
6
|
+
Project-URL: Homepage, https://www.github.com/icstos/cs-ui
|
|
7
|
+
Project-URL: Repository, https://www.github.com/icstos/cs-ui
|
|
8
|
+
Project-URL: Documentation, https://www.github.com/icstos/cs-ui
|
|
9
|
+
Project-URL: Issues, https://www.github.com/icstos/cs-ui/issues
|
|
10
|
+
Requires-Python: >=3.12
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
Requires-Dist: flet[all]==1.0.4
|
|
13
|
+
Requires-Dist: flet-code-editor
|
|
14
|
+
Requires-Dist: flet-charts
|
|
15
|
+
Requires-Dist: flet-video
|
|
16
|
+
Requires-Dist: flet-audio
|
|
17
|
+
Requires-Dist: flet-webview
|
|
18
|
+
Provides-Extra: mcp
|
|
19
|
+
Requires-Dist: fastmcp>=2.0; extra == "mcp"
|
|
20
|
+
|
|
21
|
+
# CS UI
|
|
22
|
+
|
|
23
|
+
A Python UI framework built on [Flet](https://flet.dev/), providing a rich set of pre-styled, ready-to-use components with enhanced defaults and a clean package structure.
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- **Batteries included** — `from ui import *` re-exports everything from Flet plus all CS UI components
|
|
28
|
+
- **Design tokens + Material 3 theming** — no raw color / radius / font-size literals inside
|
|
29
|
+
components. A single brand seed (`color_scheme_seed`) derives the whole M3 color scheme, so
|
|
30
|
+
light/dark and brand-color switching are **framework-level** operations, not per-widget recoloring
|
|
31
|
+
- **Inheritance-based** — static components subclass Flet native controls (e.g., `Button(ft.Button)`, `Text(ft.Text)`)
|
|
32
|
+
- **Smart defaults** — components come with sensible styling defaults (colors, sizes, border-radius, etc.) for rapid prototyping
|
|
33
|
+
- **Categorized modules** — components organized by function: chart, display, feedback, input, layout, navigation
|
|
34
|
+
- **Declarative routing** — root-view routing via `ft.Router(routes, manage_views=False)` + `page.render`
|
|
35
|
+
- **Working page overlays** — under the root-view path, `page.overlay` / `page.show_dialog` actually
|
|
36
|
+
render, so the `MultiSelect` dropdown, the `DateInput` calendar, and the `DateTimeInput`
|
|
37
|
+
calendar-plus-time-wheel panel can truly float above the content (a collapsed field is all the layout height the widget takes; opening it never pushes
|
|
38
|
+
the content below)
|
|
39
|
+
- **Two component paradigms** — static components subclass native Flet controls; interactive ones are
|
|
40
|
+
`@ft.component` functions whose state is declared with hooks (`use_state` / `use_memo` / `use_effect`)
|
|
41
|
+
- **Charts** — Bar, Line, Area, and Scatter chart wrappers via `flet-charts`, with both numeric and categorical x-axes
|
|
42
|
+
- **Desktop-grade timeline** — `Timeline` supports three alignments (rail on the left / rail on the
|
|
43
|
+
right / alternating around a centered rail); the timestamp can sit in its own column on the
|
|
44
|
+
opposite side (the default, VS Code style), above the title, inline, or be hidden. Dots come with
|
|
45
|
+
semantic colors, three variants (filled / outlined / plain) and three sizes; `done` turns into a
|
|
46
|
+
check mark automatically and `pending` appends an "in progress" hollow ring. Rows are clickable
|
|
47
|
+
end to end — hover highlight and click ripple are painted by Material's `ink`, so nothing is
|
|
48
|
+
re-rendered from Python and long lists stay smooth
|
|
49
|
+
|
|
50
|
+
## Requirements
|
|
51
|
+
|
|
52
|
+
- Python >= 3.12
|
|
53
|
+
- flet[all] ~= 1.0.4
|
|
54
|
+
- flet-code-editor
|
|
55
|
+
- flet-charts
|
|
56
|
+
- flet-video / flet-audio / flet-webview
|
|
57
|
+
|
|
58
|
+
## Installation
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
uv pip install cs-ui
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Or install from source in editable mode:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git clone https://github.com/icstos/cs-ui.git
|
|
68
|
+
cd cs-ui
|
|
69
|
+
pip install -e .
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Quick Start
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
import flet as ft
|
|
76
|
+
from ui import (
|
|
77
|
+
Button,
|
|
78
|
+
Card,
|
|
79
|
+
Checkbox,
|
|
80
|
+
Column,
|
|
81
|
+
Container,
|
|
82
|
+
Divider,
|
|
83
|
+
Input,
|
|
84
|
+
Router,
|
|
85
|
+
Route,
|
|
86
|
+
Row,
|
|
87
|
+
Text,
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
@ft.component
|
|
92
|
+
def HomePage() -> ft.Control:
|
|
93
|
+
name = ft.use_ref(lambda: Input(label="Name", value="Shawn", width=260)).current
|
|
94
|
+
agree = ft.use_ref(lambda: Checkbox(label="I have read the terms")).current
|
|
95
|
+
|
|
96
|
+
# Pages return plain controls and draw their own top bar — see the notes below
|
|
97
|
+
return Container(
|
|
98
|
+
expand=True,
|
|
99
|
+
content=Column(
|
|
100
|
+
spacing=0,
|
|
101
|
+
controls=[
|
|
102
|
+
Container(
|
|
103
|
+
height=56,
|
|
104
|
+
bgcolor=ft.Colors.WHITE,
|
|
105
|
+
padding=ft.Padding.symmetric(horizontal=14),
|
|
106
|
+
content=Row(
|
|
107
|
+
vertical_alignment=ft.CrossAxisAlignment.CENTER,
|
|
108
|
+
controls=[Text("CS UI Demo", size=17, weight=ft.FontWeight.W_600)],
|
|
109
|
+
),
|
|
110
|
+
),
|
|
111
|
+
Card(
|
|
112
|
+
elevation=4,
|
|
113
|
+
content=Container(
|
|
114
|
+
padding=24,
|
|
115
|
+
border_radius=16,
|
|
116
|
+
content=Column(
|
|
117
|
+
controls=[
|
|
118
|
+
Text("CS UI declarative demo", size=24, weight=ft.FontWeight.BOLD),
|
|
119
|
+
Text("Built on flet 1.0.0.", size=14, color="#6b7280"),
|
|
120
|
+
Divider(),
|
|
121
|
+
name.ui(),
|
|
122
|
+
Row(
|
|
123
|
+
spacing=20,
|
|
124
|
+
controls=[agree.ui(), ft.Switch(label="A switch")],
|
|
125
|
+
),
|
|
126
|
+
Button("Click me", on_click=lambda _: print("clicked!")),
|
|
127
|
+
],
|
|
128
|
+
spacing=16,
|
|
129
|
+
),
|
|
130
|
+
),
|
|
131
|
+
),
|
|
132
|
+
],
|
|
133
|
+
),
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
@ft.component
|
|
138
|
+
def App() -> ft.Control:
|
|
139
|
+
return Router([Route(index=True, component=HomePage)], manage_views=False)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def main(page: ft.Page) -> None:
|
|
143
|
+
page.title = "CS UI Demo"
|
|
144
|
+
page.render(App)
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
if __name__ == "__main__":
|
|
148
|
+
ft.run(main)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
> **Render path: use `page.render` + `Router(manage_views=False)`, not `page.render_views`.**
|
|
152
|
+
>
|
|
153
|
+
> Two pitfalls we hit for real:
|
|
154
|
+
>
|
|
155
|
+
> 1. `page.render_views` (the view stack behind `Router(manage_views=True)`) **covers the entire page
|
|
156
|
+
> overlay layer** — anything appended to `page.overlay` renders zero pixels, and `page.show_dialog`
|
|
157
|
+
> is just as dead. It does **not** raise: `len(page.overlay)` is correct and callbacks still fire.
|
|
158
|
+
> Floating `MultiSelect` panels, toasts and dialogs all silently break.
|
|
159
|
+
> 2. **`ft.View` cannot be used as an ordinary control.** Under the root-view path, putting a `View`
|
|
160
|
+
> into the widget tree makes Flutter throw `Bad state: No element` on repeat and the whole page
|
|
161
|
+
> turns into a grey box. Likewise `ft.AppBar` is an `AdaptiveControl`: it only fits `View.appbar`
|
|
162
|
+
> and cannot go into `Column.controls` — draw the top bar with `Container` + `Row` instead.
|
|
163
|
+
>
|
|
164
|
+
> Migration notes: `ft.app(main)` → `ft.run(main)`; `page.add(...)` → `page.render(Component)`;
|
|
165
|
+
> `page.go(route)` → `page.navigate(route)`; hand-maintained `page.views` →
|
|
166
|
+
> `ft.Router(routes, manage_views=False)`. The bundled `ui.Button` takes its text as `content` (not `label`).
|
|
167
|
+
>
|
|
168
|
+
> Components come in two flavors: **stateless controls** (`Button` / `Table` / `Rating` …) subclass
|
|
169
|
+
> Flet controls and are usable immediately; **stateful components** (`Input` / `Checkbox` / `Switch` /
|
|
170
|
+
> `SelectBox` / `MultiSelect` …) are `@ft.observable` data objects that must be constructed and then
|
|
171
|
+
> rendered via `.ui()` — putting the object itself in the widget tree yields a blank or grey box.
|
|
172
|
+
>
|
|
173
|
+
> If the host app has to keep the view stack (`manage_views=True`), `MultiSelect` automatically
|
|
174
|
+
> degrades to **in-flow expansion** (the panel takes layout height and pushes content down); pass
|
|
175
|
+
> `float_panel=False` to opt out of the overlay explicitly.
|
|
176
|
+
|
|
177
|
+
## Package Structure
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
src/ui/
|
|
181
|
+
├── __init__.py # re-exports all of flet + every CS UI component (617 names)
|
|
182
|
+
├── app.py # legacy-style App entry point
|
|
183
|
+
├── ft_init.py # Flet initialization
|
|
184
|
+
├── theme.py # theme / palette
|
|
185
|
+
├── cli.py # CLI entry point
|
|
186
|
+
├── chart/ # Charts (via flet-charts)
|
|
187
|
+
│ ├── _data.py # shared data parsing + palette (numeric / categorical axes)
|
|
188
|
+
│ ├── bar_chart.py # BarChart
|
|
189
|
+
│ ├── line_chart.py # LineChart
|
|
190
|
+
│ ├── rea_chart.py # AreaChart
|
|
191
|
+
│ └── scatter_chart.py # ScatterChart
|
|
192
|
+
├── components/ # Reusable generic controls
|
|
193
|
+
│ └── icon_button.py # IconButton
|
|
194
|
+
├── core/ # Core utilities
|
|
195
|
+
│ ├── config.py # configuration
|
|
196
|
+
│ ├── constants.py # StyleType / FeedbackStyle / ButtonShape …
|
|
197
|
+
│ ├── float_layer.py # page overlay: overlay_usable / use_float_layer
|
|
198
|
+
│ ├── language.py # i18n
|
|
199
|
+
│ ├── logger.py # logging
|
|
200
|
+
│ ├── snackbar.py # content guard for SnackBar-based components
|
|
201
|
+
│ ├── styles.py # shared style helpers
|
|
202
|
+
│ ├── theme.py # ThemeProvider / ThemeSwitcher / use_theme
|
|
203
|
+
│ └── tokens.py # design tokens: SPACE / RADIUS / FONT_SIZE / semantic colors
|
|
204
|
+
├── data/ # Static assets (fonts, images)
|
|
205
|
+
├── display/ # Display components
|
|
206
|
+
│ ├── image.py # Image
|
|
207
|
+
│ ├── image_gridview.py # ImageGridView
|
|
208
|
+
│ ├── list_tile.py # ListTile
|
|
209
|
+
│ ├── log_container.py # LogContainer
|
|
210
|
+
│ ├── text.py # Text / Header_1..5 / Quote / Link / Code / Markdown / Json
|
|
211
|
+
│ └── media/ # Media
|
|
212
|
+
│ ├── audio.py # Audio / AudioPlayer
|
|
213
|
+
│ ├── pdf.py # Pdf
|
|
214
|
+
│ └── video.py # Video
|
|
215
|
+
├── feedback/ # Feedback & overlays
|
|
216
|
+
│ ├── alert_dialog.py # AlertDialog
|
|
217
|
+
│ ├── loading.py # Loading
|
|
218
|
+
│ ├── message.py # Message
|
|
219
|
+
│ ├── progress_bar.py # ProgressBar
|
|
220
|
+
│ └── toast.py # Toast / toast_success / toast_error …
|
|
221
|
+
├── input/ # Form inputs
|
|
222
|
+
│ ├── button.py # Button
|
|
223
|
+
│ ├── checkbox.py # Checkbox / CheckboxGroup
|
|
224
|
+
│ ├── chip.py # Chip
|
|
225
|
+
│ ├── color_picker.py # ColorPicker
|
|
226
|
+
│ ├── date_input.py # DateInput
|
|
227
|
+
│ ├── datetime_input.py # DateTimeInput
|
|
228
|
+
│ ├── file_picker.py # FilePicker / DirPicker
|
|
229
|
+
│ ├── image_picker.py # ImagePicker
|
|
230
|
+
│ ├── input.py # Input (data_type: str/int/float/file/dir)
|
|
231
|
+
│ ├── multi_select.py # MultiSelect
|
|
232
|
+
│ ├── radio.py # RadioGroup
|
|
233
|
+
│ ├── rating.py # Rating
|
|
234
|
+
│ ├── search_bar.py # SearchBar
|
|
235
|
+
│ ├── segmented_button.py # SegmentedButton
|
|
236
|
+
│ ├── select_box.py # SelectBox
|
|
237
|
+
│ ├── slider.py # Slider
|
|
238
|
+
│ └── switch.py # Switch
|
|
239
|
+
├── layout/ # Layout & containers
|
|
240
|
+
│ ├── card.py # Card
|
|
241
|
+
│ ├── column.py # Column
|
|
242
|
+
│ ├── container.py # Container
|
|
243
|
+
│ ├── divider.py # Divider
|
|
244
|
+
│ ├── expander.py # Expander
|
|
245
|
+
│ ├── grid_view.py # GridView
|
|
246
|
+
│ ├── list_view.py # ListView
|
|
247
|
+
│ ├── page.py # PageLayout
|
|
248
|
+
│ ├── row.py # Row
|
|
249
|
+
│ ├── stack.py # Stack
|
|
250
|
+
│ ├── table.py # Table (with paging)
|
|
251
|
+
│ ├── tabs.py # Tabs / Tab / TabBar / TabBarView
|
|
252
|
+
│ ├── time_line.py # Timeline / TimelineItem
|
|
253
|
+
│ └── view.py # View
|
|
254
|
+
├── navigation/ # Navigation
|
|
255
|
+
│ ├── app_bar.py # AppBar
|
|
256
|
+
│ ├── bread_crumb.py # BreadCrumb / Crumb
|
|
257
|
+
│ └── paging.py # Paging / PagingState
|
|
258
|
+
└── utils/ # Utilities
|
|
259
|
+
├── code_editor.py # Code
|
|
260
|
+
├── code_view.py # CodeView
|
|
261
|
+
└── componts.py # Helper components
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
## Component Overview
|
|
265
|
+
|
|
266
|
+
| Category | Components |
|
|
267
|
+
|----------|-----------|
|
|
268
|
+
| **Core** | ThemeProvider, ThemeSwitcher, `use_theme`, `theme_state` |
|
|
269
|
+
| **Chart** | BarChart, LineChart, AreaChart, ScatterChart |
|
|
270
|
+
| **Display** | Image, ImageGridView, ListTile, LogContainer, Text / Header_1..5 / Quote / Link / Code / Markdown / Json |
|
|
271
|
+
| **Display / Media** | Audio, AudioPlayer, Video, Pdf |
|
|
272
|
+
| **Feedback** | AlertDialog, Loading, Message, ProgressBar, Toast |
|
|
273
|
+
| **Input** | Button, Checkbox / CheckboxGroup, Chip, ColorPicker, DateInput, DateTimeInput, FilePicker / DirPicker, ImagePicker, Input, MultiSelect, RadioGroup, Rating, SearchBar, SegmentedButton, SelectBox, Slider, Switch |
|
|
274
|
+
| **Layout** | Card, Column, Container, Divider, Expander, GridView, ListView, PageLayout, Row, Stack, Table, Tabs, Timeline, View |
|
|
275
|
+
| **Navigation** | AppBar, BreadCrumb, Paging |
|
|
276
|
+
|
|
277
|
+
**Two paradigms**:
|
|
278
|
+
- **Static components** (`Button` / `Table` / `Rating` / `Timeline` / charts …) subclass Flet controls and are ready to use.
|
|
279
|
+
- **Interactive components** (`Input` / `Checkbox` / `Switch` / `SelectBox` / `MultiSelect` / `Pdf` …) are
|
|
280
|
+
`@ft.component` functions; their state is declared with hooks and the return value goes straight into the tree.
|
|
281
|
+
|
|
282
|
+
## Design Tokens and Theming
|
|
283
|
+
|
|
284
|
+
Components never contain raw color / radius / font-size literals — everything comes from
|
|
285
|
+
`ui.core.tokens`. Switching theme and brand color is therefore a **framework-level**
|
|
286
|
+
operation rather than per-widget recoloring.
|
|
287
|
+
|
|
288
|
+
### Apply a theme
|
|
289
|
+
|
|
290
|
+
Wrap the root view in `ThemeProvider`; `build` returns your router:
|
|
291
|
+
|
|
292
|
+
```python
|
|
293
|
+
import flet as ft
|
|
294
|
+
from ui import ThemeProvider
|
|
295
|
+
|
|
296
|
+
def App() -> ft.Control:
|
|
297
|
+
return ThemeProvider(
|
|
298
|
+
build=lambda: ft.Router(ROUTES, not_found=NotFoundPage, manage_views=False)
|
|
299
|
+
)
|
|
300
|
+
|
|
301
|
+
def main(page: ft.Page):
|
|
302
|
+
page.render(App)
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
`ThemeProvider` builds the subtree with `use_memo(build, [])` — **switching the theme does not
|
|
306
|
+
rebuild the widget tree**, so values already typed into a form survive the switch
|
|
307
|
+
(verified on a real device: after switching to dark, the `use_state` value is intact).
|
|
308
|
+
|
|
309
|
+
### Light/dark and brand color
|
|
310
|
+
|
|
311
|
+
```python
|
|
312
|
+
from ui import use_theme, ThemeSwitcher, PRIMARY_SEEDS
|
|
313
|
+
|
|
314
|
+
@ft.component
|
|
315
|
+
def TopBar() -> ft.Control:
|
|
316
|
+
state = use_theme() # subscribe (must be called inside a component)
|
|
317
|
+
ft.Button("toggle", on_click=lambda e: state.toggle_mode())
|
|
318
|
+
ft.Button("recolor", on_click=lambda e: state.set_primary(PRIMARY_SEEDS["violet"]))
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
`ThemeSwitcher` is a ready-made top-bar control (brand palette + light/dark switch).
|
|
322
|
+
`ThemeState` exposes three distinct behaviors:
|
|
323
|
+
|
|
324
|
+
| Method | Behavior |
|
|
325
|
+
|--------|----------|
|
|
326
|
+
| `toggle_mode()` | always jump to the opposite of what is **currently visible** (for a ☀/🌙 button, so a click always shows a change) |
|
|
327
|
+
| `cycle_mode()` | `system → light → dark → system` (for a dropdown) |
|
|
328
|
+
| `set_mode(name)` | go straight to a mode; `"system"` follows the platform brightness |
|
|
329
|
+
| `set_primary(hex)` | swap the brand seed; the whole M3 scheme is re-derived |
|
|
330
|
+
|
|
331
|
+
### Tokens
|
|
332
|
+
|
|
333
|
+
**Theme-aware tokens** are `ft.Colors` role names resolved by Flutter at paint time, so a theme
|
|
334
|
+
switch costs **zero Python re-renders**:
|
|
335
|
+
|
|
336
|
+
```python
|
|
337
|
+
ft.Colors.PRIMARY, ft.Colors.SURFACE_CONTAINER_LOWEST, ft.Colors.ON_SURFACE_VARIANT
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
**Framework-resolved tokens** cover the semantic roles M3 does not ship (`ui.core.tokens`):
|
|
341
|
+
|
|
342
|
+
```python
|
|
343
|
+
from ui import SPACE, RADIUS, FONT_SIZE, GAP, PAD, elevation, overlay, hairline
|
|
344
|
+
|
|
345
|
+
SPACE["4"] # 16 — a 4pt scale: (0,1,2,3,4,5,6,8,10,12,16,20,24,32,40)
|
|
346
|
+
RADIUS["lg"] # 8
|
|
347
|
+
FONT_SIZE["body"] # 13
|
|
348
|
+
elevation(2) # five shadow levels, tinted with the 'shadow' role so it follows light/dark
|
|
349
|
+
overlay(0.06) # 'onsurface,0.06' — a translucent scrim that adapts automatically
|
|
350
|
+
hairline() # 1px divider
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
**Semantic colors come in three tiers** — one value cannot serve every use:
|
|
354
|
+
|
|
355
|
+
| Function | Use | Light | Dark |
|
|
356
|
+
|----------|-----|-------|------|
|
|
357
|
+
| `semantic("success")` | solid fill (badge background, status dot, progress segment) | `#047857` | `#34D399` |
|
|
358
|
+
| `on_semantic("success")` | foreground on that fill | `#FFFFFF` | `#04231A` |
|
|
359
|
+
| `semantic_text("success")` | text / icons / hairlines on the page | `#047857` | `#34D399` |
|
|
360
|
+
|
|
361
|
+
Why: measured WCAG contrast, the previous `#10B981` is only **2.54:1** on white and `#F59E0B`
|
|
362
|
+
only **2.15:1** — white text on them is equally unreadable at 2.54 / 2.15. Each tier now clears
|
|
363
|
+
4.5:1, guarded by assertions in `scripts/_theme_logic.py`.
|
|
364
|
+
|
|
365
|
+
**Available roles**: `success` / `warning` / `danger` / `info` / `neutral`.
|
|
366
|
+
|
|
367
|
+
### One important trap
|
|
368
|
+
|
|
369
|
+
In flet 1.0.4, **reading a field of an observable does not subscribe to it**. Subscription only
|
|
370
|
+
happens in three places: the component argument is an `Observable`, `use_state`, or `use_context`.
|
|
371
|
+
|
|
372
|
+
```python
|
|
373
|
+
state = theme_state()
|
|
374
|
+
mode = state.mode # ❌ just a read; nothing re-renders
|
|
375
|
+
state = use_theme() # ✅ use_context(theme_context); flet attaches the subscription
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Relatedly, theme-aware role names and Python-computed colors have very different costs: role
|
|
379
|
+
names are resolved by Flutter (free on theme switch), whereas a hex computed by
|
|
380
|
+
`semantic("success")` only updates if the component itself subscribed to the theme.
|
|
381
|
+
|
|
382
|
+
## Importing
|
|
383
|
+
|
|
384
|
+
All components can be imported directly from `ui`:
|
|
385
|
+
|
|
386
|
+
```python
|
|
387
|
+
from ui import Button, Card, Column, Container, Divider, Row, Text, TextField
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Since `ui` re-exports Flet, you can also access Flet types directly:
|
|
391
|
+
|
|
392
|
+
```python
|
|
393
|
+
from ui import ft # the flet module
|
|
394
|
+
|
|
395
|
+
# or
|
|
396
|
+
from ui import Page, Colors, Icons, MainAxisAlignment, CrossAxisAlignment
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
## Examples
|
|
400
|
+
|
|
401
|
+
Run the demo to see every component in action (11 category pages plus a 404 page):
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
python examples/demo.py
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
| Route | Contents |
|
|
408
|
+
|-------|----------|
|
|
409
|
+
| `/` | Home navigation (enter each category) |
|
|
410
|
+
| `/general` | Text / buttons / icons / chips |
|
|
411
|
+
| `/layout` | Containers / lists / tables / timeline |
|
|
412
|
+
| `/navigation` | Breadcrumb / tabs / paging |
|
|
413
|
+
| `/form` | Inputs / selectors / slider / rating |
|
|
414
|
+
| `/upload` | Files / directories / save / images |
|
|
415
|
+
| `/feedback` | Toast / message / dialog / progress |
|
|
416
|
+
| `/display` | Logs / code / images |
|
|
417
|
+
| `/charts` | Line / area / bar / scatter charts |
|
|
418
|
+
| `/media` | Audio / video / PDF |
|
|
419
|
+
| `/about` | Migration cheat-sheet and design notes |
|
|
420
|
+
|
|
421
|
+
Additional test files:
|
|
422
|
+
|
|
423
|
+
- `examples/test_home.py` — minimal home page
|
|
424
|
+
- `examples/test_form.py` — form components
|
|
425
|
+
- `examples/test_feedback.py` — feedback (dialog, snackbar, loading, progress)
|
|
426
|
+
- `examples/test_chart.py` — chart components
|
|
427
|
+
- `examples/test_line_chart.py` — line chart
|
|
428
|
+
- `examples/test_button.py` — button variants
|
|
429
|
+
- `examples/test_minimal.py` / `test_simple.py` — minimal examples
|
|
430
|
+
- `examples/my_control.py` — custom control example
|
|
431
|
+
|
|
432
|
+
## MCP server (`ui-mcp`)
|
|
433
|
+
|
|
434
|
+
An MCP server that gives AI agents *version-accurate* knowledge of this component
|
|
435
|
+
library — same idea as [flet-mcp](https://flet.dev/docs/cookbook/flet-mcp/), but for
|
|
436
|
+
`ui`. The index is built by **runtime introspection** (`@ft.control` flattens the
|
|
437
|
+
constructor and `@ft.observable` creates proxy classes, so a static scan would miss
|
|
438
|
+
the real signatures) and shipped as JSON; the server never imports `ui`.
|
|
439
|
+
|
|
440
|
+
```bash
|
|
441
|
+
pip install -e ".[mcp]"
|
|
442
|
+
ui-mcp # stdio server (default subcommand)
|
|
443
|
+
ui-mcp build # rebuild the index after changing src/ui
|
|
444
|
+
ui-mcp check # is the index older than the sources?
|
|
445
|
+
ui-mcp guide # list the curated "gotchas" topics
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
Client config:
|
|
449
|
+
|
|
450
|
+
```json
|
|
451
|
+
{ "mcpServers": { "ui": { "command": "ui-mcp" } } }
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
12 tools in five groups (`UI_MCP_ENABLE_{API,ICONS,EXAMPLES,DOCS,GUIDE}`):
|
|
455
|
+
`get_api` (primary verifier, walks base classes), `list_components`,
|
|
456
|
+
`search_components` (Chinese + English), enum tools, `find_icon`,
|
|
457
|
+
`search_examples` / `get_example` (real demo code, with per-component call sites),
|
|
458
|
+
`search_docs` / `get_doc`, and `get_guidelines` — the paradigm rules that no API
|
|
459
|
+
lookup can tell you (frozen trees, `page.render`, `#AARRGGBB` colors, design tokens).
|
|
460
|
+
|
|
461
|
+
> Adding a component? Add one line to `src/ui_mcp/aliases.py` so Chinese queries find
|
|
462
|
+
> it, then run `ui-mcp build`.
|