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#[cfg(feature = "projections")]
91pub mod projection;
92
93#[cfg(feature = "projections")]
94pub use projection::{JsonUiRenderer, RenderMode, VisualContext};
95
96/// Concise reference of all JSON-UI components for AI generation prompts.
97///
98/// Used by ferro-cli (AI view generation) and ferro-mcp (json_ui_generate tool)
99/// as shared context for LLM-based code generation.
100pub const COMPONENT_CATALOG: &str = r#"## Component Catalog
101
102### Text
103Props: content (String), element (h1|h2|h3|span|div|section|p)
104
105### Button
106Props: 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>)
107
108### Card
109Props: title (String), description (Option<String>), children (Vec<ComponentNode>), footer (Vec<ComponentNode>)
110
111### Table
112Props: 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>)
113
114### Form
115Props: action (Action), fields (Vec<ComponentNode>), method (Option<GET|POST|PUT|PATCH|DELETE>)
116
117### Input
118Props: 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>)
119
120### Select
121Props: 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>)
122
123### Alert
124Props: message (String), variant (info|success|warning|error), title (Option<String>)
125
126### Badge
127Props: label (String), variant (default|secondary|destructive|outline)
128
129### Modal
130Props: title (String), description (Option<String>), children (Vec<ComponentNode>), footer (Vec<ComponentNode>), trigger_label (Option<String>)
131
132### Checkbox
133Props: field (String), label (String), description (Option<String>), checked (Option<bool>), data_path (Option<String>), required (Option<bool>), disabled (Option<bool>), error (Option<String>)
134
135### Switch
136Props: field (String), label (String), description (Option<String>), checked (Option<bool>), data_path (Option<String>), required (Option<bool>), disabled (Option<bool>), error (Option<String>)
137
138### Separator
139Props: orientation (Option<horizontal|vertical>)
140
141### DescriptionList
142Props: items (Vec<DescriptionItem {label, value, format?}>), columns (Option<u8>)
143
144### Tabs
145Props: default_tab (String), tabs (Vec<Tab {value, label, children}>)
146
147### Breadcrumb
148Props: items (Vec<BreadcrumbItem {label, url?}>)
149
150### Pagination
151Props: current_page (u32), per_page (u32), total (u32), base_url (Option<String>)
152
153### Progress
154Props: value (u8 0-100), max (Option<u8>), label (Option<String>)
155
156### Avatar
157Props: src (Option<String>), alt (String), fallback (Option<String>), size (Option<xs|sm|default|lg>)
158
159### Skeleton
160Props: width (Option<String>), height (Option<String>), rounded (Option<bool>)
161
162## Plugin Components
163
164Plugin components use the same JSON syntax as built-in components. Their JS/CSS assets are loaded automatically.
165
166### Map
167Props: 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>)
168Example JSON: {"type": "Map", "fit_bounds": true, "markers": [{"lat": 51.5, "lng": -0.09, "popup": "Hello"}]}
169Note: Leaflet CSS/JS loaded via CDN automatically. Works inside Tabs/Modals (IntersectionObserver handles resize).
170
171## Action
172Props: 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>)
173Builders: Action::new("handler") (POST), Action::get("handler"), Action::delete("handler"), .confirm("title"), .confirm_danger("title")
174
175## ComponentNode
176Wraps every component: key (String), component (Component variant), action (Option<Action>), visibility (Option<Visibility>)
177
178## JsonUiView Builder
179JsonUiView::new().title("Title").layout("app").data(json).component(node).components(vec_of_nodes)
180"#;
ferro_json_ui/lib.rs

ferro_json_ui/
lib.rs
