Skip to content

llms.md: gaps in element surface vs. ui.* exports (follow-up to #6021) #6048

@evnchn

Description

@evnchn

Posted on behalf of @evnchn via Claude Code (Opus 4.7) — claims cross-checked against origin/main at 7916128.

TL;DR

Fresh nicegui/llms.md from #6021 reads well, but the Element Reference tables and ui.run/app.* examples miss a handful of exported public surfaces that LLMs commonly need. Opening this as a punch-list so a follow-up can decide what's worth surfacing vs. intentionally trimmed.

Exported by nicegui/ui.py but not mentioned anywhere in llms.md
Symbol What it is Why an LLM is likely to ask
ui.button_group Quasar QBtnGroup Common grouping primitive
ui.dropdown_button Split/dropdown button Common UI primitive
ui.fullscreen Fullscreen control (added 2.11.0) Frequently asked
ui.list + ui.item + ui.item_label + ui.item_section Quasar QList/QItem No Q-list pattern is shown at all
ui.keep_alive Vue <keep-alive> wrapper SPA perf escape hatch
ui.link_target In-page anchor target Pairs with documented ui.link
ui.parallax Parallax effect Niche but exported
ui.circular_progress / ui.linear_progress Progress indicators Only spinner/skeleton are mentioned today
ui.scene_view Second camera on a ui.scene Only way to reuse a scene
ui.slide_item Swipeable list item Mobile pattern
ui.timeline / ui.timeline_entry Quasar QTimeline Activity feeds
ui.run_with Mount NiceGUI inside an existing FastAPI app Integration-critical
ui.element('div', …) Generic escape hatch for arbitrary tags Used in many recipes
ui.context Current client/page context Useful in utilities
app.* helpers used in real code but not in the doc

The current doc tells LLMs to use app.mount('/static', StaticFiles(...)), which works, but skips NiceGUI's first-class helpers:

  • app.add_static_files(url_path, local_dir) / app.add_static_file(...)
  • app.add_media_files(...) / app.add_media_file(...)
  • app.on_delete(handler) — per-page-instance teardown
  • app.on_page_exception(handler) — sibling of on_exception
  • app.add_middleware(...) — the standard pattern for auth; the doc never shows how to bolt auth on
Storage table is incomplete

app.storage.browser appears in a code snippet (≈ line 635) but is missing from the storage scope/persistence table at line 131. Suggest adding a row: read-only signed cookie, survives until cookie expires.

ui.run(...) example omits flags LLMs constantly ask about

All verified to exist in nicegui/ui_run.py:

  • native=True, window_size, fullscreen, frameless, … — the entire pywebview desktop-app mode is unmentioned (and it's a flagship feature)
  • on_air='token' — NiceGUI's cloud tunneling, unmentioned
  • binding_refresh_interval — mental-model #5 references it but the ui.run block doesn't show how to set it
  • response_timeout — mental-model #10 hinges on it; not shown in the run block
  • language, tailwind, prod_js, fastapi_docs — at least worth naming
Smaller surface gaps worth a line each
  • ui.upload advanced params: auto_upload, max_file_size, max_files, max_total_size
  • ui.input(password=True, password_toggle_button=True)
  • ui.echart.from_pyecharts(...)
  • AG Grid from_pandas / run_grid_method / run_row_method
  • ui.notify(group=...) for dedup
  • ui.markdown(extras=['mermaid', 'tables', ...])

Sanity-checked as already correct

ui.timer().activate()/.deactivate()/.cancel() (timer.py:54-63), ui.sub_pages (since 2.22.0), app.storage.{user,general,client,tab,browser}, ui.fullscreen exists. No false claims spotted — this is a "missing surface" issue, not an "incorrect content" issue.

Out of scope for this issue

Whether the file should grow at all is a separate call — some of the above (parallax, keep_alive, scene_view) may have been intentionally trimmed for brevity. This list is just the punch-list so the author can decide what's worth pulling in.

cc @joko-zauberzeug (author of #6021)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationType/scope: Documentation, examples and websitereviewStatus: PR is open and needs review

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions