fluent-blue 0.1.0__tar.gz

fluent_blue-0.1.0/.gitignore

@@ -0,0 +1,87 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.venv/
+.venv*/
+venv/
+venv*/
+ENV/
+env/
+env*/
+
+# IDEs & Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+
+# PyQt / PySide specific
+*.pyc
+*.qrc.py
+*_rc.py
+ui_*.py
+!scripts/ui_audit.py
+
+# Testing & Coverage
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Linters & Formatters
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Environment variables & local secrets
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+logs/
+prompt.md
+
+site/
+.scratch/

fluent_blue-0.1.0/AGENTS.md

@@ -0,0 +1,168 @@
+# Fluent Blue: guide for AI coding agents
+
+Fluent Blue is a design system for Python desktop applications on PyQt6 and PySide6.
+
+## Rules
+
+- Import components from `fluent_blue`, and Qt names from `fluent_blue.compatibility.qt`. Never import `PyQt6` or `PySide6` directly in library code, and never load both in one process.
+- Style through props and design tokens. Do not call `setStyleSheet` on components, and do not hardcode colors, spacing, radii or fonts.
+- Read theme values with `ThemeManager.color("role")`, `.qcolor("role")`, `.spacing(step)`, `.radius("md")` and `.font("role")`. For custom painting, read them inside `paintEvent`.
+- Subclass with `ThemedMixin`, call `self.bind_theme()`, and rebuild cached pixmaps in `refresh_theme()`, so that runtime theme switches work.
+- Never connect a lambda or closure that captures a widget to `ThemeManager` signals: it outlives the widget, and PyQt aborts when it fires. Use `ThemedMixin` or a bound method.
+- Keep theme switches fast: do not rebuild child widgets in `refresh_theme()`, and free one-shot menus and dialogs with `WA_DeleteOnClose` or `finished.connect(dialog.deleteLater)`.
+- Use icon names from `icon_names()`, or add one with `register_icon`. Icon-only controls need a `tooltip`, which also becomes the accessible name.
+- Text needs at least 4.5:1 contrast. Keep keyboard access and visible focus.
+- Fluent Blue signals and methods use `snake_case`. Inherited Qt API stays `camelCase`.
+- Verify your change on both bindings: `FLUENT_BLUE_QT_BINDING=PyQt6 pytest` and `FLUENT_BLUE_QT_BINDING=PySide6 pytest`, then `python scripts/ui_audit.py`. Never report a result you did not run.
+
+## Quick start
+
+```python
+from fluent_blue import Button, Card, ThemeManager
+from fluent_blue.compatibility.qt import QApplication, QVBoxLayout
+
+app = QApplication([])
+ThemeManager.set_theme("light")
+card = Card()
+layout = QVBoxLayout(card)
+layout.addWidget(Button("Get Started", variant="primary"))
+card.show()
+app.exec()
+```
+
+## Component briefs
+
+Read the brief for a component before you use or change it. Print one with `python -m fluent_blue.agent_prompts <Name>`.
+
+### Buttons
+
+- [`Button`](docs/ai/components/Button.md): A push button with variants, sizes, icons and a loading state.
+- [`DangerButton`](docs/ai/components/DangerButton.md): A destructive action, such as deleting data.
+- [`GhostButton`](docs/ai/components/GhostButton.md): A low-emphasis action for toolbars and dense layouts.
+- [`IconButton`](docs/ai/components/IconButton.md): A square icon-only button.
+- [`LoadingButton`](docs/ai/components/LoadingButton.md): A primary button with start() and stop() shortcuts for async work.
+- [`OutlineButton`](docs/ai/components/OutlineButton.md): A brand-tinted action with less weight than PrimaryButton.
+- [`PrimaryButton`](docs/ai/components/PrimaryButton.md): The single most important action in a view.
+- [`SecondaryButton`](docs/ai/components/SecondaryButton.md): A standard action. This is the default look of Button.
+- [`SplitButton`](docs/ai/components/SplitButton.md): Primary action on the left, a menu of related actions on the right.
+- [`TextButton`](docs/ai/components/TextButton.md): A link-like action, typically inline with content.
+
+### Inputs
+
+- [`ClearableInput`](docs/ai/components/ClearableInput.md): An Input with the clear button on by default.
+- [`FormField`](docs/ai/components/FormField.md): Label, control, helper text and error message as one unit.
+- [`Input`](docs/ai/components/Input.md): A text input with icons, a clear button and validation state.
+- [`InputGroup`](docs/ai/components/InputGroup.md): Joins an input with text or widget addons inside a single border.
+- [`NumberInput`](docs/ai/components/NumberInput.md): A numeric input with bounds, steppers and arrow key support.
+- [`OtpInput`](docs/ai/components/OtpInput.md): A multi-slot numeric OTP / 2FA code entry widget with auto-focus and paste support.
+- [`PasswordInput`](docs/ai/components/PasswordInput.md): A masked input with a visibility toggle.
+- [`SearchInput`](docs/ai/components/SearchInput.md): A clearable search field that debounces typing.
+- [`TagInput`](docs/ai/components/TagInput.md): An input field that converts typed text into removable tags on Enter or comma.
+- [`TextArea`](docs/ai/components/TextArea.md): A multi-line plain text input.
+
+### Selection
+
+- [`Checkbox`](docs/ai/components/Checkbox.md): A checkbox, with optional indeterminate state.
+- [`ComboBox`](docs/ai/components/ComboBox.md): An editable Select with type-ahead; free text is allowed.
+- [`MultiSelect`](docs/ai/components/MultiSelect.md): Choose any number of values from a checkable popup list.
+- [`RadioButton`](docs/ai/components/RadioButton.md): A radio button. Use RadioGroup for the common case.
+- [`RadioGroup`](docs/ai/components/RadioGroup.md): A set of mutually exclusive radio buttons.
+- [`SegmentedControl`](docs/ai/components/SegmentedControl.md): A compact, mutually exclusive option strip.
+- [`Select`](docs/ai/components/Select.md): Choose one value from a list.
+- [`Slider`](docs/ai/components/Slider.md): A value slider.
+- [`SpinBox`](docs/ai/components/SpinBox.md): An integer input with stepper buttons.
+- [`Switch`](docs/ai/components/Switch.md): An animated on/off toggle.
+
+### Navigation
+
+- [`Breadcrumb`](docs/ai/components/Breadcrumb.md): A trail of links to parent locations; the last entry is the current page.
+- [`CommandPalette`](docs/ai/components/CommandPalette.md): A searchable command launcher.
+- [`DropdownMenu`](docs/ai/components/DropdownMenu.md): A button that opens a Menu.
+- [`Menu`](docs/ai/components/Menu.md): A popup menu.
+- [`MenuItem`](docs/ai/components/MenuItem.md): A menu entry.
+- [`NavigationBar`](docs/ai/components/NavigationBar.md): A horizontal application bar with title, start, center and end regions.
+- [`Pagination`](docs/ai/components/Pagination.md): Page navigation with ellipsis and optional range text.
+- [`Sidebar`](docs/ai/components/Sidebar.md): A vertical, sectioned, collapsible navigation rail.
+- [`SidebarItem`](docs/ai/components/SidebarItem.md): One navigation entry.
+- [`TabBar`](docs/ai/components/TabBar.md): A standalone tab strip with an underline indicator.
+- [`Tabs`](docs/ai/components/Tabs.md): Tabbed pages built on QTabWidget, using TabBar.
+
+### Data Display
+
+- [`Avatar`](docs/ai/components/Avatar.md): A user image or initials.
+- [`AvatarGroup`](docs/ai/components/AvatarGroup.md): Overlapping avatars with a "+N" overflow.
+- [`Badge`](docs/ai/components/Badge.md): A small status label or dot.
+- [`BadgeOverlay`](docs/ai/components/BadgeOverlay.md): Wraps any child widget and pins a Badge to its top-right corner.
+- [`Card`](docs/ai/components/Card.md): A content container.
+- [`CircularProgress`](docs/ai/components/CircularProgress.md): A circular progress indicator, which also serves as a spinner.
+- [`ConsoleWidget`](docs/ai/components/ConsoleWidget.md): A high-performance rich console / terminal widget for desktop tools and logging.
+- [`Divider`](docs/ai/components/Divider.md): A separator line, optionally with centered text.
+- [`EmptyState`](docs/ai/components/EmptyState.md): Explains why a view is empty and what to do next.
+- [`ListItem`](docs/ai/components/ListItem.md): One row of a list.
+- [`Popover`](docs/ai/components/Popover.md): A floating panel anchored to a widget. It closes on outside click or Escape.
+- [`ProgressBar`](docs/ai/components/ProgressBar.md): A horizontal progress bar.
+- [`Result`](docs/ai/components/Result.md): The outcome of an operation.
+- [`Skeleton`](docs/ai/components/Skeleton.md): A placeholder with a soft shimmer while content loads. The timer stops while hidden.
+- [`StatisticCard`](docs/ai/components/StatisticCard.md): A headline metric with trend.
+- [`Tag`](docs/ai/components/Tag.md): A compact label for categories, optionally closable.
+- [`Text`](docs/ai/components/Text.md): A label bound to a typography role and a text color role.
+- [`Timeline`](docs/ai/components/Timeline.md): A vertical sequence of events.
+- [`Tooltip`](docs/ai/components/Tooltip.md): Attach a rich, delayed tooltip to a widget. It also appears on keyboard focus.
+
+### Data Tables
+
+- [`Column`](docs/ai/components/Column.md): Describes one table column.
+- [`DataTable`](docs/ai/components/DataTable.md): A table with sorting, filtering, paging, selection, column control and export.
+
+### Feedback
+
+- [`Alert`](docs/ai/components/Alert.md): An inline message in the page flow.
+- [`ConfirmDialog`](docs/ai/components/ConfirmDialog.md): Ask the user to confirm an action.
+- [`LoadingOverlay`](docs/ai/components/LoadingOverlay.md): Blocks a widget and shows a spinner while it is busy.
+- [`MessageDialog`](docs/ai/components/MessageDialog.md): A modal with a status icon, a message and buttons.
+- [`Notification`](docs/ai/components/Notification.md): A richer message with a title and an action, which stays until dismissed by default.
+- [`ProgressDialog`](docs/ai/components/ProgressDialog.md): A modal that reports the progress of a long operation.
+- [`Snackbar`](docs/ai/components/Snackbar.md): A single-line message at the bottom center, often offering an undo.
+- [`Toast`](docs/ai/components/Toast.md): A brief, auto-dismissing message in the window's top right corner.
+
+### Layout
+
+- [`CollapsiblePanel`](docs/ai/components/CollapsiblePanel.md): A panel whose content expands and collapses.
+- [`Container`](docs/ai/components/Container.md): Centers content and limits its width, keeping long lines readable on wide screens.
+- [`Drawer`](docs/ai/components/Drawer.md): A panel that slides in from the edge of a window.
+- [`FluentWindow`](docs/ai/components/FluentWindow.md): A frameless base window styled with Fluent Blue design language.
+- [`Grid`](docs/ai/components/Grid.md): A grid with a fixed column count, or responsive columns from a minimum width.
+- [`Modal`](docs/ai/components/Modal.md): A themed modal dialog over a dimmed parent window.
+- [`Panel`](docs/ai/components/Panel.md): A titled section with a header action area.
+- [`ScrollArea`](docs/ai/components/ScrollArea.md): A frameless scroll area with themed scrollbars and a resizable content widget.
+- [`Splitter`](docs/ai/components/Splitter.md): A resizable split view.
+- [`Stack`](docs/ai/components/Stack.md): Arranges children in a row or column with token spacing.
+- [`TitleBar`](docs/ai/components/TitleBar.md): Custom titlebar with native-like window management buttons, draggable area, and branding.
+
+### Advanced Components
+
+- [`Calendar`](docs/ai/components/Calendar.md): A month view. Arrow keys move, Enter selects and Page Up/Down change the month.
+- [`CodeEditor`](docs/ai/components/CodeEditor.md): A code editor with line numbers, syntax colors and smart indentation.
+- [`ColorPicker`](docs/ai/components/ColorPicker.md): A swatch button that opens a saturation/value square, hue bar, hex field and presets.
+- [`DatePicker`](docs/ai/components/DatePicker.md): A date field with a popup calendar.
+- [`FilePicker`](docs/ai/components/FilePicker.md): A path field with a browse button and drag and drop.
+- [`FileTree`](docs/ai/components/FileTree.md): A lazily loaded file system tree, using QFileSystemModel.
+- [`ImageViewer`](docs/ai/components/ImageViewer.md): An image viewer with zoom, pan, rotate and fit.
+- [`LogViewer`](docs/ai/components/LogViewer.md): A live log view with level filtering, search and tailing.
+- [`RichTextEditor`](docs/ai/components/RichTextEditor.md): A rich text editor with a formatting toolbar.
+- [`Stepper`](docs/ai/components/Stepper.md): Shows progress through ordered steps. Arrow keys move when clickable.
+- [`TimePicker`](docs/ai/components/TimePicker.md): A time field with hour and minute columns.
+- [`TreeView`](docs/ai/components/TreeView.md): A tree from nested dicts, with built-in filtering.
+- [`Wizard`](docs/ai/components/Wizard.md): A multi-step flow with a stepper, validation and navigation.
+
+### Uncatalogued
+
+- [`Command`](docs/ai/components/Command.md): An entry in the palette. action runs when the command is chosen.
+- [`DataTableModel`](docs/ai/components/DataTableModel.md): Serves rows after filter, sort and page.
+- [`FieldLabel`](docs/ai/components/FieldLabel.md): The label of a FormField.
+- [`FieldMessage`](docs/ai/components/FieldMessage.md): Helper or validation text under a field.
+- [`FloatingTooltip`](docs/ai/components/FloatingTooltip.md): The window drawn by Tooltip.
+- [`RichTextArea`](docs/ai/components/RichTextArea.md): The editing surface of RichTextEditor.
+- [`SyntaxHighlighter`](docs/ai/components/SyntaxHighlighter.md): Regex-based highlighter whose colors come from theme roles.
+- [`TimePopup`](docs/ai/components/TimePopup.md): Hour and minute columns used by TimePicker.
+- [`ToastCard`](docs/ai/components/ToastCard.md): The card behind Toast, Notification and Snackbar.

fluent_blue-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes are documented here. The project follows [Semantic Versioning](https://semver.org/); until 1.0, breaking changes bump the minor version.
+
+## 0.1.0 - 2026-11-04
+
+### Added
+
+- Design tokens for color, typography, spacing, radius, elevation and motion, with per-theme overrides.
+- Runtime theme engine with light, dark and high-contrast themes, `system` following, and custom theme registration that derives a full ramp from one primary color.
+- An original set of 131 SVG icons with theme-aware rendering, caching and icon registration.
+- 103 components: buttons, inputs, selection, navigation, data display, a model/view `DataTable`, feedback, layout and advanced widgets (`DatePicker`, `Calendar`, `TimePicker`, `ColorPicker`, `FilePicker`, `ImageViewer`, `CodeEditor`, `LogViewer`, `TreeView`, `FileTree`, `Stepper`, `Wizard`, `RichTextEditor`).
+- Fluent Blue Design Studio: an interactive showcase with live previews, generated Properties and Signals tabs, copyable code, an AI Prompt tab, a Themes page with a custom theme builder and a Playground.
+- Briefs for AI coding agents (`AGENTS.md`, `llms.txt`, `docs/ai/components/`), generated from the source and checked by tests.
+- Support for PyQt6 and PySide6 from one code base, tested on both.
+- A UI audit (`scripts/ui_audit.py`) that measures clipped text, overlaps and rendered contrast on every Studio page, and a performance report (`scripts/perf_report.py`).
+- Six runnable examples, documentation built with MkDocs Material, and CI for Linux, Windows and macOS.
+
+### Performance
+
+- Theme switching restyles the application in one pass and takes about 80 ms with the Studio open; it previously took more than three seconds with every page built.
+- Icons, fonts and parsed colors are cached; hidden widgets refresh lazily when shown.
+- Design Studio builds component pages progressively and frees hidden pages before a theme switch.

fluent_blue-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to Fluent Blue
+
+Thank you for helping. This guide explains how the project is organised, what a change needs before it is merged, and how to add a component.
+
+## Set up
+
+```bash
+git clone https://github.com/danieldev23/fluent-blue
+cd fluent-blue
+python -m venv .venv-pyqt && .venv-pyqt/bin/pip install -e ".[dev,pyqt6]"
+python -m venv .venv-pyside && .venv-pyside/bin/pip install -e ".[dev,pyside6]"
+```
+
+Two environments, because the library must work on both bindings and they cannot share a process.
+
+## Before you open a pull request
+
+Run all of these. CI runs them too, but it is faster to find problems locally.
+
+```bash
+ruff check .
+.venv-pyqt/bin/pytest
+.venv-pyside/bin/pytest
+QT_QPA_PLATFORM=offscreen .venv-pyqt/bin/python scripts/ui_audit.py --deep
+.venv-pyqt/bin/python -m fluent_blue.agent_prompts --export .
+.venv-pyqt/bin/python scripts/generate_docs.py --markdown-only
+```
+
+The last two regenerate files that tests compare against the source. Commit their output.
+
+Do not report a result you did not run. If something cannot be verified on your machine, say so in the pull request.
+
+## Rules of the code base
+
+- Import Qt from `fluent_blue.compatibility.qt`, never from `PyQt6` or `PySide6` directly.
+- Components read design tokens; they never hardcode colors, spacing, radii or fonts, and never call `setStyleSheet`.
+- Styling lives in `fluent_blue/themes/stylesheet/`, keyed by class name and dynamic properties such as `variant`.
+- Custom-painted widgets read `ThemeManager` colors inside `paintEvent`. Cached assets are rebuilt in `refresh_theme()` of a `ThemedMixin` subclass.
+- Never connect a lambda that captures a widget to a `ThemeManager` signal. The connection outlives the widget and aborts the process when it fires.
+- Fluent Blue methods and signals are `snake_case`; inherited Qt API stays `camelCase`.
+- Text must reach 4.5:1 contrast in every built-in theme. `tests/test_contrast.py` checks the token pairs; the UI audit checks rendered pixels.
+- One-shot menus and dialogs free themselves (`WA_DeleteOnClose`, or `finished.connect(dialog.deleteLater)`), so long sessions do not slow down.
+
+## Adding a component
+
+1. Implement it in the matching `fluent_blue/components/<group>/` module with a docstring that has `Args:` and `Signals:` sections. The documentation, Design Studio and AI briefs are generated from these.
+2. Export it from the group's `__init__.py`.
+3. Add stylesheet rules to `fluent_blue/themes/stylesheet/<group>.py`.
+4. Add a catalog entry in `fluent_blue/studio/catalog/<group>.py`: a runnable snippet that assigns a widget to `demo`, plus one or two usage tips. The snippet is executed by the tests on both bindings and in every theme, shown live in Design Studio, printed in the docs and embedded in the AI brief.
+5. Write tests for behaviour and signals in `tests/`.
+6. Run the checks above and regenerate briefs and docs.
+
+## Commit messages
+
+Use the imperative mood and explain why, not just what. Reference issues where they exist.
+
+## Reporting bugs
+
+Open an issue with the binding and versions (`python -c "import fluent_blue as f; print(f.BINDING, f.BINDING_VERSION, f.QT_VERSION)"`), the operating system, a minimal snippet, and what you expected. A screenshot helps for visual problems.

fluent_blue-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluent Blue contributors
+
+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.