Utility component contracts (outline)¶
Stability
Classifications for this surface are recorded in STABILITY.md. Package maturity (Beta/Alpha) is separate from API level (beta / experimental / internal / deferred).
Status: Accepted
Outline page
Short summary of utility built-ins — not a full Parameters/Returns contract for each symbol. Prefer the component catalog for props and Autodoc for generated signatures.
Example¶
Utility components retain semantic text and accessible status even without browser enhancement:
from hedron import Card, Grid, JSONViewer, Metric, Progress, Stack, Status
def deployment_snapshot():
return Grid(
Card(
Metric("Deployments", 42, delta="+5", delta_tone="up"),
title="This week",
),
Card(
Stack(
Progress(68, label="68 percent deployed"),
Status("Deploying to region 3 of 4", variant="activity"),
),
title="Current rollout",
),
Card(
JSONViewer({"release": "1.0.0", "token": "redacted automatically"}),
title="Last check",
),
columns={"base": 1, "md": 3},
)
JSONViewer redacts keys containing secret, password, or token, but that is a display
guard—not permission to pass credentials into presentation data.
Constructors (summary)¶
| Component | Key parameters | Returns / notes |
|---|---|---|
Metric(label, value, delta=...) |
label, value, optional delta | Semantic value + change (not color-only) |
FileUpload(accept=..., maximum_size=...) |
accept, size hint | Markup is advisory — enforce with validate_upload_size in the route |
DownloadButton(href=..., filename=...) |
href or source=, filename |
Pair with safe_download_response for path/auth |
CodeViewer(code, language=...) |
code, language | Escaped; optional highlighting extra |
JSONViewer(value) |
structured value | Bounded, escaped; secrets redacted |
Progress(value, maximum=...) |
value, maximum | Accessible progress |
Status(...) |
state text | Live-region friendly status |
Toast(...) |
message | Non-blocking announcement |
Expander(...) / Tabs(...) |
children | Semantic disclosure / tabs + keyboard |
Sidebar(...) |
children | Complementary / navigation region |
Grid(columns=..., children=...) |
columns, children | Explicit layout (no mutable column handles) |
Errors / policy¶
| Situation | Behavior |
|---|---|
Upload over maximum_size (enforced in route) |
Application returns 4xx via validate_upload_size |
| Download path outside allowlist | safe_download_response refuses |
| Untrusted HTML in viewers | Escaped / not executed |
All components have server-rendered useful fallbacks. Browser enhancement may preserve transient interaction state but cannot become an application-wide store. Uploads/downloads require explicit authorization and resource limits.