ferro_json_ui/
lib.rs

1//! # Ferro JSON-UI
2//!
3//! Stable JSON-based server-driven UI schema types for the Ferro framework.
4//!
5//! This crate defines the typed foundation for JSON-UI: a declarative
6//! component system where the server sends JSON descriptions that are
7//! rendered to HTML. Components, actions, and visibility rules are all
8//! defined as Rust types with serde serialization and JSON Schema generation.
9//!
10//! ## Schema Structure
11//!
12//! A JSON-UI view consists of:
13//! - **Components** - UI elements (Card, Table, Form, Button, etc.)
14//! - **Actions** - Handler references with confirmations and outcomes
15//! - **Visibility** - Conditional rendering based on data conditions
16//! - **View** - Top-level container with layout and title
17//!
18//! ## Example
19//!
20//! ```rust
21//! use ferro_json_ui::{JsonUiView, ComponentNode, Component, CardProps};
22//!
23//! let view = JsonUiView::new()
24//!     .title("Users")
25//!     .component(ComponentNode {
26//!         key: "header".to_string(),
27//!         component: Component::Card(CardProps {
28//!             title: "User Management".to_string(),
29//!             description: None,
30//!             children: vec![],
31//!             max_width: None,
32//!             footer: vec![],
33//!         }),
34//!         action: None,
35//!         visibility: None,
36//!     });
37//!
38//! let json = view.to_json().unwrap();
39//! assert!(json.contains("\"$schema\":\"ferro-json-ui/v1\""));
40//! ```
41
42pub mod action;
43pub mod component;
44pub mod config;
45pub mod data;
46pub mod layout;
47pub mod plugin;
48pub mod plugins;
49pub mod render;
50pub mod resolve;
51pub mod view;
52pub mod visibility;
53
54pub(crate) mod runtime;
55
56pub use action::{Action, ActionOutcome, ConfirmDialog, DialogVariant, HttpMethod, NotifyVariant};
57pub use component::{
58    ActionCardProps, ActionCardVariant, AlertProps, AlertVariant, AvatarProps, BadgeProps,
59    BadgeVariant, BreadcrumbItem, BreadcrumbProps, ButtonGroupProps, ButtonProps, ButtonType,
60    ButtonVariant, CardProps, CheckboxProps, ChecklistItem, ChecklistProps, CollapsibleProps,
61    Column, ColumnFormat, Component, ComponentNode, DataTableProps, DescriptionItem,
62    DescriptionListProps, DropdownMenuAction, DropdownMenuProps, EmptyStateProps, FormMaxWidth,
63    FormProps, FormSectionProps, GapSize, GridProps, HeaderProps, IconPosition, ImageProps,
64    InputProps, InputType, KanbanBoardProps, KanbanColumnProps, ModalProps,
65    NotificationDropdownProps, NotificationItem, Orientation, PageHeaderProps, PaginationProps,
66    PluginProps, ProductTileProps, ProgressProps, SelectOption, SelectProps, SeparatorProps,
67    SidebarGroup, SidebarNavItem, SidebarProps, Size, SkeletonProps, SortDirection, StatCardProps,
68    SwitchProps, Tab, TableProps, TabsProps, TextElement, TextProps, ToastProps, ToastVariant,
69};
70pub use config::JsonUiConfig;
71// resolve_path and resolve_path_string are pub(crate) — internal render pipeline helpers
72pub use layout::{
73    register_layout, render_layout, DashboardLayout, DashboardLayoutConfig, Layout, LayoutContext,
74    LayoutRegistry, NavItem, SidebarSection,
75};
76// AppLayout, AuthLayout, DefaultLayout are pub in layout.rs but not user-facing — users select
77// layouts by name string ("dashboard", "app", "auth"), not by struct.
78// navigation, sidebar, footer, global_registry are framework-internal.
79pub use plugin::{
80    collect_plugin_assets, global_plugin_registry, register_plugin, registered_plugin_types,
81    with_plugin, Asset, CollectedAssets, JsonUiPlugin, PluginRegistry,
82};
83pub use plugins::{register_built_in_plugins, MapPlugin};
84pub use render::{render_to_html, render_to_html_with_plugins, RenderResult};
85// collect_plugin_types is pub(crate) — internal render pipeline helper
86pub use resolve::{resolve_actions, resolve_actions_strict, resolve_errors, resolve_errors_all};
87pub use view::{JsonUiView, SCHEMA_VERSION};
88pub use visibility::{Visibility, VisibilityCondition, VisibilityOperator};
89
90/// Concise reference of all JSON-UI components for AI generation prompts.
91///
92/// Used by ferro-cli (AI view generation) and ferro-mcp (json_ui_generate tool)
93/// as shared context for LLM-based code generation.
94pub const COMPONENT_CATALOG: &str = r#"## Component Catalog
95
96### Text
97Props: content (String), element (h1|h2|h3|span|div|section|p)
98
99### Button
100Props: label (String), variant (default|secondary|destructive|outline|ghost|link), size (xs|sm|default|lg), disabled (Option<bool>), icon (Option<String>), icon_position (Option<left|right>)
101
102### Card
103Props: title (String), description (Option<String>), children (Vec<ComponentNode>), footer (Vec<ComponentNode>)
104
105### Table
106Props: columns (Vec<Column {key, label, format?}>), data_path (String), row_actions (Option<Vec<Action>>), empty_message (Option<String>), sortable (Option<bool>), sort_column (Option<String>), sort_direction (Option<asc|desc>)
107
108### Form
109Props: action (Action), fields (Vec<ComponentNode>), method (Option<GET|POST|PUT|PATCH|DELETE>)
110
111### Input
112Props: field (String), label (String), input_type (text|email|password|number|textarea|hidden|date|time|url|tel|search), placeholder (Option<String>), required (Option<bool>), disabled (Option<bool>), error (Option<String>), description (Option<String>), default_value (Option<String>), data_path (Option<String>), step (Option<String>)
113
114### Select
115Props: field (String), label (String), options (Vec<SelectOption {value, label}>), placeholder (Option<String>), required (Option<bool>), disabled (Option<bool>), error (Option<String>), description (Option<String>), default_value (Option<String>), data_path (Option<String>)
116
117### Alert
118Props: message (String), variant (info|success|warning|error), title (Option<String>)
119
120### Badge
121Props: label (String), variant (default|secondary|destructive|outline)
122
123### Modal
124Props: title (String), description (Option<String>), children (Vec<ComponentNode>), footer (Vec<ComponentNode>), trigger_label (Option<String>)
125
126### Checkbox
127Props: field (String), label (String), description (Option<String>), checked (Option<bool>), data_path (Option<String>), required (Option<bool>), disabled (Option<bool>), error (Option<String>)
128
129### Switch
130Props: field (String), label (String), description (Option<String>), checked (Option<bool>), data_path (Option<String>), required (Option<bool>), disabled (Option<bool>), error (Option<String>)
131
132### Separator
133Props: orientation (Option<horizontal|vertical>)
134
135### DescriptionList
136Props: items (Vec<DescriptionItem {label, value, format?}>), columns (Option<u8>)
137
138### Tabs
139Props: default_tab (String), tabs (Vec<Tab {value, label, children}>)
140
141### Breadcrumb
142Props: items (Vec<BreadcrumbItem {label, url?}>)
143
144### Pagination
145Props: current_page (u32), per_page (u32), total (u32), base_url (Option<String>)
146
147### Progress
148Props: value (u8 0-100), max (Option<u8>), label (Option<String>)
149
150### Avatar
151Props: src (Option<String>), alt (String), fallback (Option<String>), size (Option<xs|sm|default|lg>)
152
153### Skeleton
154Props: width (Option<String>), height (Option<String>), rounded (Option<bool>)
155
156## Plugin Components
157
158Plugin components use the same JSON syntax as built-in components. Their JS/CSS assets are loaded automatically.
159
160### Map
161Props: center (Option<[f64; 2]>), zoom (u8 0-18, default 13), height (String, default "400px"), fit_bounds (Option<bool>), markers (Vec<{lat, lng, popup?, color?, popup_html?, href?}>), tile_url (Option<String>), attribution (Option<String>), max_zoom (Option<u8>)
162Example JSON: {"type": "Map", "fit_bounds": true, "markers": [{"lat": 51.5, "lng": -0.09, "popup": "Hello"}]}
163Note: Leaflet CSS/JS loaded via CDN automatically. Works inside Tabs/Modals (IntersectionObserver handles resize).
164
165## Action
166Props: handler (String "controller.method" format), method (GET|POST|PUT|PATCH|DELETE), confirm (Option<ConfirmDialog {title, message?, variant: default|danger}>), on_success (Option<ActionOutcome>), on_error (Option<ActionOutcome>)
167Builders: Action::new("handler") (POST), Action::get("handler"), Action::delete("handler"), .confirm("title"), .confirm_danger("title")
168
169## ComponentNode
170Wraps every component: key (String), component (Component variant), action (Option<Action>), visibility (Option<Visibility>)
171
172## JsonUiView Builder
173JsonUiView::new().title("Title").layout("app").data(json).component(node).components(vec_of_nodes)
174"#;
ferro_json_ui/lib.rs

ferro_json_ui/
lib.rs
