cs-ui 0.1.0__py3-none-any.whl

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.
Files changed (104) hide show
  1. cs_ui-0.1.0.dist-info/METADATA +462 -0
  2. cs_ui-0.1.0.dist-info/RECORD +104 -0
  3. cs_ui-0.1.0.dist-info/WHEEL +5 -0
  4. cs_ui-0.1.0.dist-info/entry_points.txt +3 -0
  5. cs_ui-0.1.0.dist-info/top_level.txt +2 -0
  6. ui/__init__.py +30 -0
  7. ui/app.py +249 -0
  8. ui/chart/__init__.py +12 -0
  9. ui/chart/_data.py +347 -0
  10. ui/chart/bar_chart.py +269 -0
  11. ui/chart/line_chart.py +395 -0
  12. ui/chart/rea_chart.py +244 -0
  13. ui/chart/scatter_chart.py +202 -0
  14. ui/cli.py +2 -0
  15. ui/components/icon_button.py +25 -0
  16. ui/core/__init__.py +104 -0
  17. ui/core/config.py +42 -0
  18. ui/core/constants.py +74 -0
  19. ui/core/float_layer.py +185 -0
  20. ui/core/language.py +0 -0
  21. ui/core/logger.py +163 -0
  22. ui/core/snackbar.py +70 -0
  23. ui/core/styles.py +150 -0
  24. ui/core/theme.py +383 -0
  25. ui/core/tokens.py +278 -0
  26. ui/display/__init__.py +48 -0
  27. ui/display/echarts.py +1 -0
  28. ui/display/image.py +78 -0
  29. ui/display/image_gridview.py +234 -0
  30. ui/display/list_tile.py +6 -0
  31. ui/display/log_container.py +91 -0
  32. ui/display/media/__init__.py +15 -0
  33. ui/display/media/audio.py +167 -0
  34. ui/display/media/pdf.py +237 -0
  35. ui/display/media/video.py +106 -0
  36. ui/display/text.py +120 -0
  37. ui/feedback/__init__.py +27 -0
  38. ui/feedback/alert_dialog.py +213 -0
  39. ui/feedback/loading.py +15 -0
  40. ui/feedback/message.py +120 -0
  41. ui/feedback/progress_bar.py +18 -0
  42. ui/feedback/toast.py +230 -0
  43. ui/ft_init.py +538 -0
  44. ui/input/__init__.py +44 -0
  45. ui/input/button.py +235 -0
  46. ui/input/calendar_panel.py +407 -0
  47. ui/input/checkbox.py +184 -0
  48. ui/input/chip.py +168 -0
  49. ui/input/color_picker.py +1474 -0
  50. ui/input/date_input.py +460 -0
  51. ui/input/datetime_input.py +821 -0
  52. ui/input/file_picker.py +213 -0
  53. ui/input/image_picker.py +58 -0
  54. ui/input/input.py +299 -0
  55. ui/input/multi_select.py +633 -0
  56. ui/input/panel_field.py +363 -0
  57. ui/input/radio.py +98 -0
  58. ui/input/rating.py +89 -0
  59. ui/input/search_bar.py +25 -0
  60. ui/input/segmented_button.py +60 -0
  61. ui/input/select_box.py +100 -0
  62. ui/input/slider.py +189 -0
  63. ui/input/switch.py +75 -0
  64. ui/layout/__init__.py +39 -0
  65. ui/layout/card.py +58 -0
  66. ui/layout/column.py +20 -0
  67. ui/layout/container.py +29 -0
  68. ui/layout/divider.py +16 -0
  69. ui/layout/expander.py +572 -0
  70. ui/layout/grid_view.py +8 -0
  71. ui/layout/list_view.py +8 -0
  72. ui/layout/page.py +166 -0
  73. ui/layout/row.py +11 -0
  74. ui/layout/stack.py +11 -0
  75. ui/layout/table.py +270 -0
  76. ui/layout/tabs.py +68 -0
  77. ui/layout/time_line.py +729 -0
  78. ui/layout/view.py +11 -0
  79. ui/navigation/__init__.py +7 -0
  80. ui/navigation/app_bar.py +6 -0
  81. ui/navigation/bread_crumb.py +177 -0
  82. ui/navigation/paging.py +300 -0
  83. ui/theme.py +1 -0
  84. ui/utils/__init__.py +4 -0
  85. ui/utils/code_editor.py +7 -0
  86. ui/utils/code_view.py +18 -0
  87. ui/utils/componts.py +40 -0
  88. ui_mcp/__about__.py +7 -0
  89. ui_mcp/__init__.py +27 -0
  90. ui_mcp/__main__.py +6 -0
  91. ui_mcp/aliases.py +152 -0
  92. ui_mcp/build.py +112 -0
  93. ui_mcp/cli.py +153 -0
  94. ui_mcp/data/api.json +1 -0
  95. ui_mcp/data/docs.json +1 -0
  96. ui_mcp/data/examples.json +1 -0
  97. ui_mcp/docs.py +230 -0
  98. ui_mcp/examples.py +339 -0
  99. ui_mcp/guidelines.py +288 -0
  100. ui_mcp/introspect.py +745 -0
  101. ui_mcp/paths.py +69 -0
  102. ui_mcp/search.py +79 -0
  103. ui_mcp/server.py +471 -0
  104. ui_mcp/store.py +557 -0
@@ -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`.
@@ -0,0 +1,104 @@
1
+ ui/__init__.py,sha256=rvs3f32ts4p5_I6oudyaTbOccqafcz3bPpqjoRP2DHU,903
2
+ ui/app.py,sha256=_Uv_qedaaI52AvPpYngoMTuSQwhgHZD6Lc2pGq1SOaU,8667
3
+ ui/cli.py,sha256=zeBCm6VHgIlBm4o2eX90CJVUkUYjxzIFTgTdbrLkmv0,21
4
+ ui/ft_init.py,sha256=KQP7MPUkPNU1VxmNFbKJtal6uNo8QMb539CHpciDOaQ,18361
5
+ ui/theme.py,sha256=DkeLUlrb7rGx3nZ04aADU9HXXu5mZTf_DBwT0xhzIv4,7
6
+ ui/chart/__init__.py,sha256=4mYGwL8_9kQeYWS1I7pRjPU37XMtzYg2ZVNe2IYsBCo,371
7
+ ui/chart/_data.py,sha256=l7L9dLqzzU8o6WuTQP0htFvgRjylRTRuZBK3t4H2HEY,11798
8
+ ui/chart/bar_chart.py,sha256=Yx3unjz2ZwVDz88nXnUWYOBg7lFo7ANIztP0WK_Gt5s,9185
9
+ ui/chart/line_chart.py,sha256=WOxDTTS0V7xG27cUWzXMk0f_o5xGPtdx1stwtJ7I7vg,14026
10
+ ui/chart/rea_chart.py,sha256=BllbURTNdNgL19m0idVbnVjjlkyxiFceuhnelG-rqE0,8802
11
+ ui/chart/scatter_chart.py,sha256=DkjyQlBH8v8g7Vr_XaWZ3RrVYH_ptmqAtF2dnl4dsoQ,6759
12
+ ui/components/icon_button.py,sha256=dECODtVd8wzqfV9_VVPTYiklxcTnNLsUFb8GT9pZtHY,699
13
+ ui/core/__init__.py,sha256=qy3ZNL-0yl-v9R4AZONF7roRB_O1JzHl61tXP1fhLV0,1962
14
+ ui/core/config.py,sha256=bhC8sQRN86DSSB22IXXf9iKWpyGkBMR_oN8HZ74Txyo,913
15
+ ui/core/constants.py,sha256=XtssyE1QpYqbb2hIMsU1gWbnBrh2fkbGUUPJgEPf_4k,1476
16
+ ui/core/float_layer.py,sha256=GBvXcBBWPtG3E0llrjzzPkTFVKAkfIH-ko9aPdEgTNg,6821
17
+ ui/core/language.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
18
+ ui/core/logger.py,sha256=DrgZquD0jBJxV4SJ_1Aa3gfIXpGSE5E8zRIdtfKE61c,4793
19
+ ui/core/snackbar.py,sha256=kBYg69EP9FyiRs8ni-cq1AFrNMg5wYxpBrET9GHH02M,2744
20
+ ui/core/styles.py,sha256=pxn3bmzl-di0fTXqP_Lg_37l8Q89pGx1acc2vVK3M84,5287
21
+ ui/core/theme.py,sha256=znkLaiTEngGMWvXv6oXzE2GZDLnfpEH7yiXX7ygbbrg,15334
22
+ ui/core/tokens.py,sha256=KgoPTfw7DcgjF_bVL-H7x3FHA2HOY_Y4X8AWAnyzH40,11411
23
+ ui/display/__init__.py,sha256=vHIGbZznOV1-XZb2_hT6N6VjF_xktLnti4WJSghZfGA,894
24
+ ui/display/echarts.py,sha256=J8uSdSV2xjIGzzafAelD3g3B1hP-Zp6zQiBG2CJQfq4,8
25
+ ui/display/image.py,sha256=DdQP4R2-Kq_so2DvGhy-9hFaRUJsJucjc2jVXzGygeY,2177
26
+ ui/display/image_gridview.py,sha256=FyBb760wuFJg_dI0fjvl7EVQnIZDzs4SkiFbY9y45rE,7916
27
+ ui/display/list_tile.py,sha256=QR4IGuWNRiDL2WIEGI6ciptW5fljA7XOlXFh-chlDi4,70
28
+ ui/display/log_container.py,sha256=xILIMFcLBPycrGQl4sJ-WY-bOOZ6cQb6K_N-N3Ky_SY,2815
29
+ ui/display/text.py,sha256=0Kv33JYS20abTA4GLIkIXs24mf3K4B-X7RZB32RHMMI,3041
30
+ ui/display/media/__init__.py,sha256=Qb-_USQ_sdLsjeoOYXpabI8hwz9ohQlW2p5NGrAMOTs,304
31
+ ui/display/media/audio.py,sha256=X0Z5cUws2V2Gjz_x5_tOv6-iI_AuWODfVoEQhCoVvoc,5386
32
+ ui/display/media/pdf.py,sha256=urQXxIsUI4p8fLRuU1OCJv6g1xBomG6akB6QEKWozLU,8749
33
+ ui/display/media/video.py,sha256=Jc_p3d2pIV_eYyzuJMAcx317oDqKjWdfJy_fc9-e3aE,3656
34
+ ui/feedback/__init__.py,sha256=Y8FZBAKICFc08spuT4F8qEd2U5amrvW6v8eA1rOnLyY,518
35
+ ui/feedback/alert_dialog.py,sha256=utIdCsm5c_gF98SK_3HoGgBPwXIs5Q6sihqWNUVtUQg,6850
36
+ ui/feedback/loading.py,sha256=tBEWFY1lz03fcsx35Z_xzH5c1mpN13aLI_15HxMSdgw,342
37
+ ui/feedback/message.py,sha256=mSsd_LMOim9-W9lI8PE_kNUaHV61KcTDo774SEPMyUE,4179
38
+ ui/feedback/progress_bar.py,sha256=EH3k9BPy2GcMG1zqItVw-JhWCW1y1OC_M40aSvPa0JQ,631
39
+ ui/feedback/toast.py,sha256=LdTdhyLU_CMB1Fp1dpNS_u155g3FXLQEtGrz0JGgjJ0,7993
40
+ ui/input/__init__.py,sha256=V0eLLyppX6eppeUAv54lq6AmtOKLIyOnOf2ZSGxM1nU,1120
41
+ ui/input/button.py,sha256=PCRz42UUL3qDj5XAptbaHHnsZzyywvKvHamphKTgBCk,9545
42
+ ui/input/calendar_panel.py,sha256=wgrrLGu2uh4jTvjkAHvnfUIxPvzNl3NnbofhjBRUvLI,16888
43
+ ui/input/checkbox.py,sha256=-aLLSh_CKnsvoHg-e15DU-wTA-ou8ry6v8AXJQr6CkM,5348
44
+ ui/input/chip.py,sha256=i0a5Venajl-hYu02IjQMcRjfi1LX-vSAKQe4sLn2drQ,5265
45
+ ui/input/color_picker.py,sha256=wR0XxgUsqodd_KPZQUMMYcy0Mj5a_KNtp5RVyyGlkes,60577
46
+ ui/input/date_input.py,sha256=xJgxiS4yNUywZh2W59N-xTR5i8qCbWcokWtlcL8IDuI,18894
47
+ ui/input/datetime_input.py,sha256=TMVkjEPwRZx1g8cdkbdoLlmpwhYauXCag4T-wFMbeTg,33966
48
+ ui/input/file_picker.py,sha256=pBtLhkGKS02DPKZal8Er21kE4svZAGp8c06GFLQwjqI,6368
49
+ ui/input/image_picker.py,sha256=1sNlQs2JPqM__ksu1hctA-UyqdNcv5xtSAsFRRI2mpM,1548
50
+ ui/input/input.py,sha256=SSedmffbNfJEMOdEsfVH53GnUIIIB-EGY5qZW5oxSSA,10795
51
+ ui/input/multi_select.py,sha256=sXKgzQB-vDL9BlgmmwphaZ6I78HCl3eoCQoaRYU4f50,23719
52
+ ui/input/panel_field.py,sha256=Qmf19lBwRx9lfLInIGKWHj6ys8wKugtNKCsom1_miQw,16004
53
+ ui/input/radio.py,sha256=TWw77n476Jn_sLTRXJXA43deYzuU8ztHYUSK4Kci0Xo,2626
54
+ ui/input/rating.py,sha256=Evu01AwgkJ2nyO1JAz_vD44gjL6dSAhg5-gfLaZS1nE,2908
55
+ ui/input/search_bar.py,sha256=0VM6-iwFbP54owkop-ciwfvHXUH86KChKfIQM8vcRT4,564
56
+ ui/input/segmented_button.py,sha256=drLL1N6J-86OmF5EkQtTOJQf0C2D7SQO0EsE67IrZTs,1739
57
+ ui/input/select_box.py,sha256=kRneX_h07x5jRJXbqMAcNVS0Q5Pnb_GBI6R0H72Us-4,2733
58
+ ui/input/slider.py,sha256=O4m1Pu1iGIfSGl-TPLzXTxgUjsKy5p8rgN19BMAJs5o,6187
59
+ ui/input/switch.py,sha256=tEtWARCe0QPziRldtS7wI2j_ArLwXnVCwc-h2_Wk0ys,1909
60
+ ui/layout/__init__.py,sha256=eliYyU-f8PjhJSC-bNR4NatWmgZ7Gevgi_3gem3cwPA,859
61
+ ui/layout/card.py,sha256=ID18PKmQAyek3WtJhl3EAkD-imgyBqrJ5fFP-4DudUw,1952
62
+ ui/layout/column.py,sha256=izapt7egdYxBcnNk5Zg3uA83m4F_mQ6ibuHcR8iabmI,239
63
+ ui/layout/container.py,sha256=kZdIE7giztO4xlw85r00Oi_r1X7oLiHFeax85Te1ZAM,526
64
+ ui/layout/divider.py,sha256=GviZvKU-rqTavY8JQy_0PiVZrl8jhInrokqe-QKQqW4,170
65
+ ui/layout/expander.py,sha256=MJwmdZFLZ6B7f-kJvLUjlkTQn4Lp6Umjo7s9-GIwNVU,25355
66
+ ui/layout/grid_view.py,sha256=Ktn5_enoYthEm1EwIq_ZrMpI8X3nwnTx1_qpW73f6vo,102
67
+ ui/layout/list_view.py,sha256=yGitWbPqaj5Sax4AOkHY4-Vn7OKRyDoRTj4IYGlSlc4,102
68
+ ui/layout/page.py,sha256=HDOGZFqtakG7vJHr2qqrtwTLUIXQiis_XsUI9QuSOaY,5312
69
+ ui/layout/row.py,sha256=ja_J9kraxcK2vwYsxyO-fWPR1Us-OHQ2_HnX9NKUpc0,76
70
+ ui/layout/stack.py,sha256=hMbiXmRYJZzFIuK19Nq8HcOGkn8UhIpM1bJmPz82Ja8,82
71
+ ui/layout/table.py,sha256=2Qeb2sUjVBtMg0inmfliwwtU5OMQtI3Qmep-DpfEeto,9551
72
+ ui/layout/tabs.py,sha256=fxflu94R7hoMvM7iVUODrLgJ36sWH-vV8KCsiM_mZEY,1492
73
+ ui/layout/time_line.py,sha256=91G59Z28yHh2zfET3Iuni9SaJDiTlxlPEFF-XKLqIkQ,30120
74
+ ui/layout/view.py,sha256=zkggaf8q9HAPr_ydadAV3n1IPenP-432XGjyOViYV-M,79
75
+ ui/navigation/__init__.py,sha256=sYE2coWzdZNY3BYNZQUlV2aKNkDl6HA_UwO2A1_hAYU,240
76
+ ui/navigation/app_bar.py,sha256=ki1_J8yg6QhpFF7Ms6sDOZMnsxq0EBlYAUeczXBB3ok,66
77
+ ui/navigation/bread_crumb.py,sha256=oFPzep8dLDb2IK9yVVExrZKfRJQGhfkE2QDkHGA9FG0,5715
78
+ ui/navigation/paging.py,sha256=q-3FHlBHMEbaBhsoM3aBtRavcqyeTMRYcMbfNoZoVNk,10633
79
+ ui/utils/__init__.py,sha256=5IbbS8KJzcno2G-7Qql-6Ezq4SNqXzyThKSj3M4Ssyg,106
80
+ ui/utils/code_editor.py,sha256=v7WflWK-zfhpHHRRgQfSO2vbX9ndxak-GNWJedXJrpM,106
81
+ ui/utils/code_view.py,sha256=RILug3Ahir8u_Rizletmrfq2ihkUq7O_xMyNIQetH_Q,458
82
+ ui/utils/componts.py,sha256=CM_5h43Mixh0YLDScnhQOiDgCVv0lacg4ZPr7gFU27M,912
83
+ ui_mcp/__about__.py,sha256=oLaQbZ7u3-2J7mgK2xqqIw8u7VbKNS2RvWHYLTFW_uI,235
84
+ ui_mcp/__init__.py,sha256=CBuQpyWkDlbkIDFpT3f6nhTzliW5WycOPZ3IF2qKA1g,1072
85
+ ui_mcp/__main__.py,sha256=A7qhiCnPgKIdZxootVPXzvqge9lXNwIjRxEwRRisyU8,126
86
+ ui_mcp/aliases.py,sha256=SpHLg4F7G4Zi5L5lQM4CnBRUz-lxw43D7kG-tDmE4K0,8350
87
+ ui_mcp/build.py,sha256=8R055FKN9pPVlBE00Q-IenPt5UXvSEDxzdu5niSt2L4,4175
88
+ ui_mcp/cli.py,sha256=Vi42WpME_sJMpvwCbvPB8mbjbVOGBHDzpb4mNXbMq74,5658
89
+ ui_mcp/docs.py,sha256=BZ4oSvFn93x0TYJHv2muKCbgDxyOdwOjK34xqeZlZRM,7677
90
+ ui_mcp/examples.py,sha256=Bn-o9IF42s1RHJXDFssyPs7BFwTGgYfGeNAmEJZdWJw,12114
91
+ ui_mcp/guidelines.py,sha256=UHxO60_KLKOuYr9kNFZ-7D0libLxA7yyv6s_MH-z0Do,14321
92
+ ui_mcp/introspect.py,sha256=2DVv2Rer0tGoEGXol3tKIYk6gOPQAFbCaDuIGK-AtS0,27131
93
+ ui_mcp/paths.py,sha256=kFEtRW_E0Gy7iEptepJWrek3a6YxDfhOfG-OOPGWpuw,1996
94
+ ui_mcp/search.py,sha256=yTIYVRZN8pL0bcMXLen6cGOZcA6fn31h4z13gz8s6yk,2862
95
+ ui_mcp/server.py,sha256=_2Syry_XQo4v6a-WtYOo11esSTeRltkhxfOWzm_fLk0,17380
96
+ ui_mcp/store.py,sha256=jJc9iKMPNTFCYmCsyg7F4WQznJhdfuoozrcRzE7Ha4E,21955
97
+ ui_mcp/data/api.json,sha256=viZiRq90TJgC_fFE5NRYpmUxoXKzNCPZi5IaUx0rVAs,268208
98
+ ui_mcp/data/docs.json,sha256=lpDzqUQ120p4dUWmPNFhEOZQN25vGDAvfjeya71rVno,168841
99
+ ui_mcp/data/examples.json,sha256=xpNhOIA57pc90NrQDN2PFH0rI5QtkCc6IYBaJvgTROY,183634
100
+ cs_ui-0.1.0.dist-info/METADATA,sha256=-7cv1ir6efFmYbD6xdwIjaaVwgZqWstPjy4ombTFTaM,20870
101
+ cs_ui-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
102
+ cs_ui-0.1.0.dist-info/entry_points.txt,sha256=tzDE7vW-R4IUuUIoT4xLqkPT2JVlneC9Q9yDx1fjoNc,71
103
+ cs_ui-0.1.0.dist-info/top_level.txt,sha256=59Zp8GBIYEstInlkZgDTQPXZFzD82esPD1b6euGwhj4,10
104
+ cs_ui-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ moss-tts-nano = ui.cli:main
3
+ ui-mcp = ui_mcp.cli:main
@@ -0,0 +1,2 @@
1
+ ui
2
+ ui_mcp
ui/__init__.py ADDED
@@ -0,0 +1,30 @@
1
+ from .ft_init import *
2
+ from flet import *
3
+ from flet import canvas
4
+
5
+ from .chart import *
6
+ from .core import *
7
+ from .display import *
8
+ from .feedback import *
9
+ from .input import *
10
+ from .layout import *
11
+ from .navigation import *
12
+ from .utils import *
13
+
14
+ from .app import App
15
+
16
+
17
+ # 手动
18
+ # ⚠️ 不要在这里写 `__name__ = "cs-ui"`。
19
+ # `from ui import X` 在 X 不存在时,CPython 的 _handle_fromlist 会用
20
+ # `f"{module.__name__}.{X}"` 去 import 子模块;一旦 __name__ 被改成 "cs-ui",
21
+ # 报错就变成极具误导性的 `ModuleNotFoundError: No module named 'cs-ui'`,
22
+ # 真正缺失的名字(例如已下线的 ECharts)完全看不出来。
23
+ # 产品名放独立字段,别占用 __name__。
24
+ __pkg_name__ = "cs-ui"
25
+ __version__ = "0.0.5"
26
+ __author__ = "Shawn Chen"
27
+ __email__ = "cs@cstos.com"
28
+ __copyright__ = "Shawn Chen"
29
+ __description__ = ""
30
+ __url__ = "https://github.com/icstos/cs-ui"