feat: initial project setup with implementation plan
- Add PLAN.md with 40-step checklist across 10 phases - Add CLAUDE.md with project-specific instructions - Set up nix flake with FastHTML/MonsterUI dependencies - Create Python package skeleton (src/animaltrack) - Vendor FastHTML and MonsterUI documentation - Add Docker build configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
449
docs/vendor/monsterui/examples/tutorial_layout.md
vendored
Normal file
449
docs/vendor/monsterui/examples/tutorial_layout.md
vendored
Normal file
@@ -0,0 +1,449 @@
|
||||
# MonterUI Page Layout Guide
|
||||
|
||||
This guide will discuss 3 tools for laying out your app pages, Grid, Flexbox, and Columns. This page will discuss the strengths and when to use each individually, and then a section for how to combine them for more complex layouts at the end.
|
||||
|
||||
> Note: This guide is designed to get you started building layouts quickly, not to teach you all the details needed to build every possible custom layout with pixel-perfect control. To get more detailed and lower-level control, explore the tailwind docs.
|
||||
|
||||
This guide is for creating flexible layouts you envision, but does not discuss responsiveness to make different layouts that are both mobile and desktop friendly. Stay tunes for a responsiveness guide that will help with that!
|
||||
|
||||
# Grid
|
||||
|
||||
Grids are best for regular predictable layouts with lots of the same shape of things that may need to change a lot for different screen sizes. I think the best way to see what it can do is to see a bunch of examples, so here they are!
|
||||
|
||||
## Minimal Image Cards
|
||||
|
||||
This is a minimal example of a grid that just shows image and text. This is the foundation for many more complex layouts so make sure to understand what's going on here first before moving on!
|
||||
|
||||
A grid lays things out in a...grid. As you can see, we have evenly sized cards by default.
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
Image 0
|
||||
|
||||
Image 1
|
||||
|
||||
Image 2
|
||||
|
||||
Image 3
|
||||
|
||||
Image 4
|
||||
|
||||
Image 5
|
||||
|
||||
[code]
|
||||
|
||||
def picsum_img(seed): return Img(src=f'https://picsum.photos/300/200?random={seed}')
|
||||
|
||||
Grid(*[Card(picsum_img(i),P(f"Image {i}")) for i in range(6)])
|
||||
[/code]
|
||||
|
||||
## Dashboard Example
|
||||
|
||||
However, they don't have to be evenly sized! By providing `row-span-{int}` and `col-span-{int}` we can control how many rows or columns specific grid elements take up. By doing this, we can create a grid that has lots of different shapes and types of elements.
|
||||
|
||||
Let's look at a dashboard layout at an examples of this.
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
### SideBar
|
||||
|
||||
Range For Filters
|
||||
|
||||
A search Bar
|
||||
|
||||
Choose Product Line
|
||||
|
||||
Product Line AProduct Line BProduct Line CProduct Line D
|
||||
|
||||
Include Inactive Users
|
||||
|
||||
Include Users without order
|
||||
|
||||
Include Users without email
|
||||
|
||||
Total Users
|
||||
|
||||
### 1,234
|
||||
|
||||
Active Now
|
||||
|
||||
### 342
|
||||
|
||||
Revenue
|
||||
|
||||
### $45,678
|
||||
|
||||
Conversion
|
||||
|
||||
### 2.4%
|
||||
|
||||
### Monthly Revenue
|
||||
|
||||
Chart Goes Here
|
||||
|
||||
### User Growth
|
||||
|
||||
Chart Goes Here
|
||||
|
||||
[code]
|
||||
|
||||
def StatCard(title, value, color='primary'):
|
||||
"A card with a statistics. Since there is no row/col span class it will take up 1 slot"
|
||||
return Card(P(title, cls=TextPresets.muted_sm), H3(value, cls=f'text-{color}'),)
|
||||
|
||||
stats = [StatCard(*data) for data in [
|
||||
("Total Users", "1,234", "blue-600"),
|
||||
("Active Now", "342", "green-600"),
|
||||
("Revenue", "$45,678", "purple-600"),
|
||||
("Conversion", "2.4%", "amber-600")]]
|
||||
|
||||
def ChartCard(title):
|
||||
"A card for a chart. col-span-2 means it will take up 2 columns"
|
||||
return Div(cls="col-span-2")(
|
||||
Card(H3(title),Div("Chart Goes Here", cls="h-64 uk-background-muted")))
|
||||
chart_cards = [ChartCard(title) for title in ("Monthly Revenue", "User Growth")]
|
||||
|
||||
|
||||
sidebar = Form(
|
||||
H3("SideBar"),
|
||||
LabelRange("Range For Filters", min=0, max=100),
|
||||
LabelInput("A search Bar"),
|
||||
LabelSelect(map(Option, ["Product Line A", "Product Line B", "Product Line C", "Product Line D"]),
|
||||
label="Choose Product Line"),
|
||||
LabelCheckboxX("Include Inactive Users"),
|
||||
LabelCheckboxX("Include Users without order"),
|
||||
LabelCheckboxX("Include Users without email"),
|
||||
# This sidebar will take up 2 rows b/c of row-span-2
|
||||
cls='row-span-2 space-y-5'
|
||||
)
|
||||
|
||||
Container(Grid(sidebar, *stats, *chart_cards, cols=5))
|
||||
[/code]
|
||||
|
||||
# Flexbox
|
||||
|
||||
Using Grid for the overall layout, and flex for the individual elements is a powerful pattern. With `MonsterUI` you can do quite a bit without knowing anything about flexbox, which is what will be taught here.
|
||||
|
||||
However, flexbox is well worth learning about it in more detail. You will run into situations where you need more flexbox knowledge than is covered here to build your vision. Thankfully you can get that knowledge by playing a fantastic tutorial game called FlexBox Froggy!
|
||||
|
||||
## Forms
|
||||
|
||||
Often you want to stack things horizontally. You can use the `DivHStacked` component to do this.
|
||||
|
||||
`DivHStacked` is a helper function for flexbox and creates a div with these classes by default `cls=(FlexT.block, FlexT.row, FlexT.middle, 'space-x-4')`.
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
### Form with Input Groups
|
||||
|
||||
Search Users
|
||||
|
||||
Filter Tags
|
||||
|
||||
Email List
|
||||
|
||||
SubmitCancel
|
||||
|
||||
[code]
|
||||
|
||||
def InputGroup(label, placeholder='', button_text='Submit', cls=''):
|
||||
# Div H Stacked makes the label and input show up on the same row instead of putting the input on a newline
|
||||
return DivHStacked(
|
||||
FormLabel(label, cls='whitespace-nowrap'),
|
||||
Input(placeholder=placeholder))
|
||||
|
||||
Container(
|
||||
H3("Form with Input Groups"),
|
||||
Form(cls='space-y-4')(
|
||||
InputGroup("Search Users", "Enter username..."),
|
||||
InputGroup("Filter Tags", "Add tags...", "Add"),
|
||||
InputGroup("Email List", "Enter email...", "Subscribe"),
|
||||
Div(*( Button(UkIcon(icon, cls='mr-2'), text) for icon, text in [("rocket", "Submit"), ("circle-x", "Cancel")]), cls='space-x-4')))
|
||||
[/code]
|
||||
|
||||
## Avatar
|
||||
|
||||
You can use this same `DivHStacked` to align things like text next to images. And you can use `DivVStacked` to stack things vertically to create design structures you like. `DivVStacked` works by using `cls=(FlexT.block,FlexT.column,FlexT.middle)`
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
John Doe
|
||||
|
||||
[email protected]
|
||||
|
||||
+1-123-456-7890
|
||||
|
||||
[code]
|
||||
|
||||
# DivHStacked makes the a single row so text is to on same line as avatar
|
||||
DivHStacked(
|
||||
DiceBearAvatar("user"),
|
||||
# DivVStacked stacks things vertically together and centers it with flex
|
||||
DivVStacked(
|
||||
P("John Doe", cls=TextT.lg),
|
||||
P("[email protected]", cls=TextT.muted),
|
||||
P("+1-123-456-7890"), cls=TextT.muted))
|
||||
[/code]
|
||||
|
||||
## Pricing Card
|
||||
|
||||
These can be combined with icons and other styling to create larger components like a pricing card.
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
## Pro Plan
|
||||
|
||||
### $99
|
||||
|
||||
per month
|
||||
|
||||
* Unlimited users
|
||||
|
||||
* 24/7 priority support
|
||||
|
||||
* Custom branding options
|
||||
|
||||
* Advanced analytics dashboard
|
||||
|
||||
* Full API access
|
||||
|
||||
* Priority request queue
|
||||
|
||||
Subscribe Now
|
||||
|
||||
[code]
|
||||
|
||||
features = [
|
||||
"Unlimited users",
|
||||
"24/7 priority support",
|
||||
"Custom branding options",
|
||||
"Advanced analytics dashboard",
|
||||
"Full API access",
|
||||
"Priority request queue"
|
||||
]
|
||||
|
||||
|
||||
def PricingCard(plan, price, features):
|
||||
"Create a polished pricing card with consistent styling"
|
||||
return Card(
|
||||
DivVStacked( # Center and veritcally stack the plan name and price
|
||||
H2(plan),
|
||||
H3(price, cls='text-primary'),
|
||||
P('per month',cls=TextT.muted),
|
||||
cls='space-y-1'),
|
||||
# DivHStacked makes green check and feature Li show up on same row instead of newline
|
||||
Ul(*[DivHStacked(UkIcon('check', cls='text-green-500 mr-2'), Li(feature)) for feature in features],
|
||||
cls='space-y-4'),
|
||||
Button("Subscribe Now", cls=(ButtonT.primary, 'w-full')))
|
||||
|
||||
DivVStacked(PricingCard("Pro Plan", "$99", features))
|
||||
[/code]
|
||||
|
||||
## Footer
|
||||
|
||||
Or you can combine things to make advanced footers that have titles, organized links, and icons!
|
||||
|
||||
In this example we add another flex helper function, `DivFullySpaced`. `DivFullySpaced` is a flex class that puts as much space between items as possible
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
### Company Name
|
||||
|
||||
* * *
|
||||
|
||||
#### Company
|
||||
|
||||
AboutBlogCareersPress Kit
|
||||
|
||||
#### Resources
|
||||
|
||||
DocumentationHelp CenterStatusContact Sales
|
||||
|
||||
#### Legal
|
||||
|
||||
Terms of ServicePrivacy PolicyCookie SettingsAccessibility
|
||||
|
||||
* * *
|
||||
|
||||
© 2024 Company Name. All rights reserved.
|
||||
|
||||
[code]
|
||||
|
||||
def FooterLinkGroup(title, links):
|
||||
# DivVStacked centers and makes title and each link stack vertically
|
||||
return DivVStacked(
|
||||
H4(title),
|
||||
*[A(text, href=f"#{text.lower().replace(' ', '-')}", cls=TextT.muted) for text in links])
|
||||
|
||||
company = ["About", "Blog", "Careers", "Press Kit"]
|
||||
resource = ["Documentation", "Help Center", "Status", "Contact Sales"]
|
||||
legal = ["Terms of Service", "Privacy Policy", "Cookie Settings", "Accessibility"]
|
||||
|
||||
Container(cls='uk-background-muted py-12')(Div(
|
||||
# Company Name and social icons will be on the same row with as much sapce between as possible
|
||||
DivFullySpaced(
|
||||
H3("Company Name"),
|
||||
# DivHStacked makes the icons be on the same row in a group
|
||||
DivHStacked(*[UkIcon(icon, cls=TextT.lead) for icon in
|
||||
['twitter', 'facebook', 'github', 'linkedin']])),
|
||||
DividerLine(),
|
||||
DivFullySpaced( # Each child will be spread out as much as possible based on number of children
|
||||
FooterLinkGroup("Company", company),
|
||||
FooterLinkGroup("Resources", resource),
|
||||
FooterLinkGroup("Legal", legal)),
|
||||
DividerLine(),
|
||||
P("© 2024 Company Name. All rights reserved.", cls=TextT.lead+TextT.sm),
|
||||
cls='space-y-8 p-8'))
|
||||
[/code]
|
||||
|
||||
## Dashboard
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
## Welcome back, Isaac!
|
||||
|
||||
Here's what's happening with your projects today.
|
||||
|
||||
Total Projects
|
||||
|
||||
### 12
|
||||
|
||||
+2.5% from last month
|
||||
|
||||
Hours Logged
|
||||
|
||||
### 164
|
||||
|
||||
+12.3% from last month
|
||||
|
||||
Tasks Complete
|
||||
|
||||
### 64%
|
||||
|
||||
-4.1% from last month
|
||||
|
||||
Team Velocity
|
||||
|
||||
### 23
|
||||
|
||||
+8.4% from last month
|
||||
|
||||
### Recent Activity
|
||||
|
||||
Sarah Chen completed Project Alpha deployment
|
||||
|
||||
2h ago
|
||||
|
||||
James Wilson commented on Project Beta
|
||||
|
||||
4h ago
|
||||
|
||||
Maria Garcia uploaded new design files
|
||||
|
||||
6h ago
|
||||
|
||||
Alex Kumar started Sprint Planning
|
||||
|
||||
8h ago
|
||||
|
||||
[code]
|
||||
|
||||
def StatsCard(label, value, change):
|
||||
color = 'green' if change[0] == '+' else 'red'
|
||||
return Card(DivVStacked( # Stacks vertically and centers all elements
|
||||
P(label, cls=TextPresets.muted_sm),
|
||||
H3(value),
|
||||
P(f"{change}% from last month", cls=f"text-{color}-600 text-sm")))
|
||||
|
||||
def RecentActivity(user, action, time):
|
||||
return DivHStacked( # Makes Avatar and text be on same row
|
||||
DiceBearAvatar(user, h=8, w=8),
|
||||
P(f"{user} {action}", cls="flex-1"),
|
||||
P(time, cls=TextPresets.muted_sm))
|
||||
|
||||
DivVStacked( # Centers the entire dashboard layout
|
||||
# Page header
|
||||
DivVStacked( # Stacks vertically and centers the title/subtitle
|
||||
H2("Welcome back, Isaac!"),
|
||||
P("Here's what's happening with your projects today.",cls=TextT.muted)),
|
||||
|
||||
# DivHStacked puts all the stats cards on the same row
|
||||
DivHStacked(*(StatsCard(label, value, change)
|
||||
for label, value, change in [
|
||||
("Total Projects", "12", "+2.5"),
|
||||
("Hours Logged", "164", "+12.3"),
|
||||
("Tasks Complete", "64%", "-4.1"),
|
||||
("Team Velocity", "23", "+8.4")]
|
||||
)),
|
||||
|
||||
# Recent activity
|
||||
Card(*(RecentActivity(user, action, time)
|
||||
for user, action, time in [
|
||||
("Sarah Chen", "completed Project Alpha deployment", "2h ago"),
|
||||
("James Wilson", "commented on Project Beta", "4h ago"),
|
||||
("Maria Garcia", "uploaded new design files", "6h ago"),
|
||||
("Alex Kumar", "started Sprint Planning", "8h ago")]),
|
||||
header=H3("Recent Activity"),
|
||||
),
|
||||
cls="space-y-6"
|
||||
)
|
||||
[/code]
|
||||
|
||||
## Columns
|
||||
|
||||
Columns are a great for sections that have a lot of text.
|
||||
|
||||
See Source
|
||||
|
||||
See Output
|
||||
|
||||
# Lorem Ipsum
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
||||
|
||||
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
|
||||
|
||||
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.
|
||||
|
||||
Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor.
|
||||
|
||||
[code]
|
||||
|
||||
Container(
|
||||
H1("Lorem Ipsum", cls="text-center mb-8"),
|
||||
|
||||
# Use 2 columns for the main content
|
||||
Div(cls="columns-2 gap-12")(
|
||||
P("""Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
|
||||
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
|
||||
minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
|
||||
ex ea commodo consequat."""),
|
||||
|
||||
DivCentered(cls='mt-8')(
|
||||
P("""Duis aute irure dolor in reprehenderit in voluptate velit esse
|
||||
cillum dolore eu fugiat nulla pariatur.""",
|
||||
cls=(TextT.lg, TextT.bold, TextT.center, TextT.italic, "text-primary"))),
|
||||
|
||||
P("""Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
|
||||
officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde
|
||||
omnis iste natus error sit voluptatem accusantium doloremque laudantium."""),
|
||||
|
||||
P("""Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit
|
||||
aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem
|
||||
sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor.""")))
|
||||
[/code]
|
||||
|
||||
Reference in New Issue
Block a user