### Compile Primaviz Demos and Showcase

Source: https://github.com/phiat/primaviz/blob/main/README.md

Use the `just` command to compile different sets of Primaviz examples. This includes per-chart demos, a comprehensive showcase, and a full demo with all features.

```bash
just demos      # Compile all per-chart demos
just showcase   # Compile the showcase
just demo       # Compile the comprehensive demo
```

--------------------------------

### Create Theme from JSON Tokens

Source: https://github.com/phiat/primaviz/blob/main/README.md

Builds a theme from a JSON file containing design tokens. Supports light and dark themes and requires specific JSON structure.

```typst
#let tokens = json("tokens.json")
#let my-theme = theme-from-json(tokens.light)
#let my-dark = theme-from-json(tokens.dark)

#show: with-theme.with(my-theme)
```

--------------------------------

### Import Primaviz Library

Source: https://github.com/phiat/primaviz/blob/main/README.md

Import the Primaviz library to use its charting and dashboard functionalities. Ensure you are using the correct version.

```typst
#import "@preview/primaviz:0.5.3": *
```

--------------------------------

### Primaviz Development Commands

Source: https://github.com/phiat/primaviz/blob/main/README.md

Use these 'just' commands for various development tasks including compilation, live-reloading, testing, and release preparation.

```bash
just demos           # Compile all per-chart demos
```

```bash
just demo            # Compile the comprehensive demo
```

```bash
just showcase        # Compile the showcase
```

```bash
just watch           # Live-reload during development
```

```bash
just watch-demo bar  # Watch a specific demo (e.g., bar, pie, scatter)
```

```bash
just test            # Run all compilation tests
```

```bash
just check           # Full CI check (demo + demos + showcase + tests)
```

```bash
just screenshots     # Regenerate screenshots (screenshots/demo/ + screenshots/showcase/)
```

```bash
just open            # Compile and open the demo PDF
```

```bash
just dev             # Watch with live-reload and open PDF
```

```bash
just clean           # Clean generated artifacts
```

```bash
just release         # Full release prep (check + screenshots)
```

```bash
just extract-theme   # Extract CSS tokens → JSON theme via Python (e.g., just extract-theme src/index.css)
```

```bash
just extract-theme-ts # Extract CSS tokens → JSON theme via Bun/TS (same options)
```

```bash
just stats           # Show project stats
```

--------------------------------

### Apply Themes to Charts

Source: https://context7.com/phiat/primaviz/llms.txt

Use the theming system to apply preset or custom themes to charts. Set document-wide defaults using `with-theme()` or override theme properties directly.

```typst
#import "@preview/primaviz:0.5.3": *

// Available preset themes:
// themes.default, themes.minimal, themes.dark, themes.presentation,
// themes.print, themes.accessible, themes.compact

// Using a preset theme
#bar-chart(data, theme: themes.dark)

// Document-wide theme via show rule
#show: with-theme.with(themes.dark)

// Custom theme overrides
#bar-chart(
  data,
  theme: (
    palette: (rgb("#1f77b4"), rgb("#ff7f0e"), rgb("#2ca02c")),
    show-grid: true,
    background: rgb("#f8f9fa"),
    border-radius: 8pt,
  ),
)

// Scaling with seeds (golden-ratio derived)
#bar-chart(data, theme: (base-size: 12pt, base-gap: 8pt))  // larger
#bar-chart(data, theme: (base-size: 5pt, base-gap: 3pt))   // compact
```

--------------------------------

### Create Dashboard Layouts

Source: https://context7.com/phiat/primaviz/llms.txt

Utilize dashboard primitives like `card`, `compact-table`, `alert`, `badge`, and `dashboard-layout` for building report interfaces. The `dashboard-layout` allows defining grid structures with specified columns and rows.

```typst
#import "@preview/primaviz:0.5.3": *

// Card container
#card(title: "Monthly Report", desc: "January 2024")[ 
  #bar-chart(monthly-data, width: 100%, height: 150pt)
]

// Compact data table
#compact-table(
  ("Product", "Sales", "Growth"),
  (
    ("Widget A", "$12,500", "+15%"),
    ("Widget B", "$8,200", "+8%"),
    ("Widget C", "$6,100", "-3%"),
  ),
  highlight-col: 2,
)

// Alerts with variants
#alert(variant: "success", title: "Success")[Data saved successfully.]
#alert(variant: "warning")[Please review before submitting.]
#alert(variant: "error", title: "Error")[Connection failed.]

// Badges
#badge("Active", variant: "success")
#badge("Pending", variant: "secondary")
#badge("Urgent", variant: "destructive")

// Dashboard grid layout
#dashboard-layout(
  cols: (2fr, 1fr),
  gap: 12pt,
  rows: (
    (metric-row(metrics), card(title: "Summary")[...]),
    (card(title: "Chart")[#line-chart(data)], card(title: "Table")[...]),
  ),
)
```

--------------------------------

### Render Calendar Heatmap

Source: https://context7.com/phiat/primaviz/llms.txt

Creates a GitHub-style calendar heatmap to visualize daily activity. Provide dates and corresponding values. Configure cell size and labels.

```typst
#import "@preview/primaviz:0.5.3": *

#calendar-heatmap(
  (
    dates: ("2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05",
            "2024-01-06", "2024-01-07", "2024-01-08", "2024-01-09", "2024-01-10"),
    values: (3, 7, 2, 0, 5, 8, 1, 4, 6, 9),
  ),
  cell-size: 14pt,
  title: "Contribution Activity",
  palette: "heat",
  show-month-labels: true,
  show-day-labels: true
)
```

--------------------------------

### Create a Bar Chart

Source: https://github.com/phiat/primaviz/blob/main/README.md

Generates a bar chart using provided labels and values. Customize width, height, and title.

```typst
#import "@preview/primaviz:0.5.3": *

// Load data from JSON
#let data = json("mydata.json")

// Create a bar chart
#bar-chart(
  (
    labels: ("A", "B", "C", "D"),
    values: (25, 40, 30, 45),
  ),
  width: 300pt,
  height: 200pt,
  title: "My Chart",
)
```

--------------------------------

### Create a Donut Pie Chart

Source: https://github.com/phiat/primaviz/blob/main/README.md

Generates a donut pie chart with specified labels and values. Control the size of the chart.

```typst
#import "@preview/primaviz:0.5.3": *

// Create a pie chart
#pie-chart(
  (
    labels: ("Red", "Blue", "Green"),
    values: (30, 45, 25),
  ),
  size: 150pt,
  donut: true,
)
```

--------------------------------

### Custom Theme Overrides

Source: https://github.com/phiat/primaviz/blob/main/README.md

Allows partial theme customization by specifying only the desired keys. Unspecified keys inherit from the active theme.

```typst
#bar-chart(data, theme: (show-grid: true, palette: (red, blue, green)))
```

--------------------------------

### Render Metric Card

Source: https://context7.com/phiat/primaviz/llms.txt

Creates a dashboard KPI tile displaying a prominent value, label, delta, and optional trend sparkline. Use 'si' format for scientific notation and specify suffixes.

```typst
#import "@preview/primaviz:0.5.3": *

#metric-card(
  value: 12847,
  label: "Total Revenue",
  delta: 12.5,
  trend: (8200, 9100, 10300, 11200, 12100, 12847),
  width: 180pt,
  format: "si",
  suffix: " USD"
)
```

--------------------------------

### Apply Document-Wide Dark Theme

Source: https://github.com/phiat/primaviz/blob/main/README.md

Sets a default theme for all charts within a specific block using `with-theme`. Explicit chart themes override this.

```typst
// Block wrapper
#with-theme(themes.dark)[
  #bar-chart(data)       // uses dark theme
  #pie-chart(data2)      // uses dark theme
  #line-chart(data3, theme: themes.minimal) // explicit override wins
]

// Or as a show rule for the entire document
#show: with-theme.with(themes.dark)
```

--------------------------------

### Add Annotations to Line Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use the 'annotations' parameter in 'line-chart' to add reference lines, bands, and labels. Ensure the '@preview/primaviz:0.5.3' package is imported.

```typst
#import "@preview/primaviz:0.5.3": *

#line-chart(
  data,
  annotations: (
    // Horizontal reference line
    (type: "h-line", value: 75, color: red, dash: "dashed", label: "Target"),

    // Vertical reference line
    (type: "v-line", value: 3, color: blue, dash: "dotted", label: "Launch"),

    // Horizontal band/region
    (type: "h-band", from: 60, to: 80, color: green, opacity: 15%, label: "Goal Zone"),

    // Point label
    (type: "label", x: 5, y: 92, text: "Peak", color: purple),
  ),
)
```

--------------------------------

### Calendar Heatmap

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a GitHub-style calendar heatmap for visualizing daily activity patterns over time.

```APIDOC
## calendar-heatmap

### Description
Renders a GitHub-style calendar heatmap for visualizing daily activity patterns over time.

### Parameters
- **dates** (array of strings) - Required - An array of dates in YYYY-MM-DD format.
- **values** (array) - Required - An array of values corresponding to each date.
- **cell-size** (length) - Optional - The size of each day's cell.
- **title** (string) - Optional - The title of the heatmap.
- **palette** (string) - Optional - The color palette to use (e.g., "heat").
- **show-month-labels** (bool) - Optional - Whether to display month labels.
- **show-day-labels** (bool) - Optional - Whether to display day labels (e.g., Mon, Tue).

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#calendar-heatmap(
  (
    dates: ("2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05",
            "2024-01-06", "2024-01-07", "2024-01-08", "2024-01-09", "2024-01-10"),
    values: (3, 7, 2, 0, 5, 8, 1, 4, 6, 9),
  ),
  cell-size: 14pt,
  title: "Contribution Activity",
  palette: "heat",
  show-month-labels: true,
  show-day-labels: true,
)
```
```

--------------------------------

### Simple Data Format for Primaviz

Source: https://github.com/phiat/primaviz/blob/main/README.md

Use this simple data structure for charts requiring only labels and values.

```typst
(
  labels: ("Jan", "Feb", "Mar"),
  values: (100, 150, 120),
)
```

--------------------------------

### Render Responsive Metric Cards

Source: https://context7.com/phiat/primaviz/llms.txt

Use `metric-row` to display multiple metric cards side-by-side in a responsive layout. Configure gap between cards.

```typst
#import "@preview/primaviz:0.5.3": *

#metric-row(
  (
    (value: 2847, label: "Users", delta: 8.2, trend: (2100, 2300, 2500, 2700, 2847)),
    (value: 156, label: "Orders", delta: -3.1, trend: (180, 175, 168, 162, 156)),
    (value: 94.2, label: "Uptime", delta: 0.5, suffix: "%"),
    (value: 42, label: "Open Issues", delta: -15.0),
  ),
  gap: 12pt,
)
```

--------------------------------

### Load Simple Chart Data

Source: https://context7.com/phiat/primaviz/llms.txt

Use `load-simple` to convert JSON data into a format suitable for bar, pie, or line charts. It accepts key-value pairs or arrays of label-value pairs.

```typst
#import "@preview/primaviz:0.5.3": *

// Load from JSON file
#let raw = json("sales.json")

// Simple label-value data (for bar, pie, line charts)
#let data = load-simple(raw)
// Accepts: {"Jan": 300, "Feb": 400} or [["Jan", 300], ["Feb", 400]]
// Returns: (labels: ("Jan", "Feb"), values: (300, 400))
#bar-chart(data)
```

--------------------------------

### Create a Radar Chart

Source: https://github.com/phiat/primaviz/blob/main/README.md

Generates a radar chart comparing multiple series across different labels. Customize size and title.

```typst
#import "@preview/primaviz:0.5.3": *

// Create a radar chart
#radar-chart(
  (
    labels: ("STR", "DEX", "CON", "INT", "WIS", "CHA"),
    series: (
      (name: "Fighter", values: (18, 12, 16, 10, 13, 8)),
      (name: "Wizard", values: (8, 14, 12, 18, 15, 11)),
    ),
  ),
  size: 200pt,
  title: "Character Comparison",
)
```

--------------------------------

### Extract CSS Themes with Python Script

Source: https://github.com/phiat/primaviz/blob/main/README.md

Use the Python script to parse CSS custom properties and convert them into Primaviz theme files. Supports various output formats and custom dark mode selectors.

```bash
just extract-theme src/index.css                          # default: outputs typst + json to ./typst/
```

```bash
just extract-theme styles.css --name shadcn --format json  # json only, custom name
```

```bash
just extract-theme globals.css --dark-selector '[data-theme="dark"]'
```

--------------------------------

### Render Heatmap

Source: https://context7.com/phiat/primaviz/llms.txt

Displays a grid heatmap with color-coded cells and automatic value labels. Specify rows, columns, and values. Choose a palette for color mapping.

```typst
#import "@preview/primaviz:0.5.3": *

#heatmap(
  (
    rows: ("Mon", "Tue", "Wed", "Thu", "Fri"),
    cols: ("9AM", "12PM", "3PM", "6PM"),
    values: (
      (45, 82, 67, 38),
      (52, 91, 73, 41),
      (48, 78, 85, 55),
      (61, 95, 88, 62),
      (35, 72, 58, 28),
    ),
  ),
  cell-size: 40pt,
  title: "Website Traffic by Day/Hour",
  show-values: true,
  palette: "viridis",
  show-legend: true
)
```

--------------------------------

### Render Progress Bar

Source: https://context7.com/phiat/primaviz/llms.txt

Creates a horizontal progress bar with an optional value label and rounded ends. Specify the current value and maximum value.

```typst
#import "@preview/primaviz:0.5.3": *

#progress-bar(
  72,
  max-val: 100,
  width: 250pt,
  height: 24pt,
  title: "Upload Progress",
  show-value: true,
  color: rgb("#4e79a7"),
  rounded: true
)
```

--------------------------------

### Apply Preset Dark Theme to Bar Chart

Source: https://github.com/phiat/primaviz/blob/main/README.md

Applies a preset dark theme to a bar chart. The `theme` parameter accepts predefined themes like `themes.dark`.

```typst
#import "@preview/primaviz:0.5.3": *

#bar-chart(data, theme: themes.dark)
```

--------------------------------

### Load Hierarchical Data for Treemaps

Source: https://context7.com/phiat/primaviz/llms.txt

Use `load-hierarchy` to prepare hierarchical data from JSON for visualizations like treemaps or sunburst charts. The data should be structured with 'name', 'value', and 'parent' properties.

```typst
#import "@preview/primaviz:0.5.3": *

// Hierarchical data (for treemap, sunburst)
#let tree = load-hierarchy(json("org.json"))
// Accepts: [{"name": "A", "value": 10, "parent": null}, ...]
#treemap(tree)
```

--------------------------------

### Render Multi-Series Line Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use `multi-line-chart` for comparing multiple data series over time. Features include points, legends, and customizable axes.

```typst
#import "@preview/primaviz:0.5.3": *

#multi-line-chart(
  (
    labels: ("Week 1", "Week 2", "Week 3", "Week 4"),
    series: (
      (name: "Signups", values: (120, 145, 168, 195)),
      (name: "Activations", values: (95, 118, 142, 170)),
      (name: "Conversions", values: (42, 58, 72, 89)),
    ),
  ),
  width: 400pt,
  height: 250pt,
  title: "Funnel Metrics Over Time",
  show-points: true,
  show-legend: true,
  x-label: "Week",
  y-label: "Count",
)
```

--------------------------------

### Render Sparkline

Source: https://context7.com/phiat/primaviz/llms.txt

Generates a tiny inline line chart for tables or text. Supports filling the area under the line and custom colors. Useful for showing trends at a glance.

```typst
#import "@preview/primaviz:0.5.3": *

// Inline sparkline in a table
#table(
  columns: (auto, auto, auto),
  [*Metric*], [*Value*], [*Trend*],
  [Revenue], [$12.5M], [#sparkline((8, 10, 9, 12, 11, 14, 13, 15), width: 80pt, height: 20pt, fill-area: true)],
  [Users], [45K], [#sparkline((32, 35, 38, 42, 40, 45), width: 80pt, height: 20pt)],
  [Conversion], [3.2%], [#sparkline((2.8, 2.9, 3.0, 3.1, 3.0, 3.2), width: 80pt, height: 20pt, color: green)]
)
```

--------------------------------

### Accessing Colors from Primaviz Themes

Source: https://github.com/phiat/primaviz/blob/main/README.md

Use the `get-color` function to retrieve specific colors from any loaded Primaviz theme, including default and custom presets.

```typst
#import "@preview/primaviz:0.5.3": get-color, themes

// Default palette
#get-color(themes.default, 0)  // blue
#get-color(themes.default, 1)  // orange
#get-color(themes.default, 2)  // red

// Or use a theme preset
#get-color(themes.dark, 0)  // cyan
```

--------------------------------

### Bubble Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a bubble chart where each point has x, y, and size dimensions with smart label deconfliction.

```APIDOC
## bubble-chart

### Description
Renders a bubble chart where each point has x, y, and size dimensions with smart label deconfliction.

### Parameters
- **x** (array) - Required - Array of x-axis values.
- **y** (array) - Required - Array of y-axis values.
- **size** (array) - Required - Array of values determining the size of each bubble.
- **width** (length) - Optional - The width of the chart.
- **height** (length) - Optional - The height of the chart.
- **title** (string) - Optional - The title of the chart.
- **x-label** (string) - Optional - Label for the x-axis.
- **y-label** (string) - Optional - Label for the y-axis.
- **size-label** (string) - Optional - Label for the size dimension.
- **min-radius** (length) - Optional - The minimum radius for bubbles.
- **max-radius** (length) - Optional - The maximum radius for bubbles.
- **show-labels** (bool) - Optional - Whether to display labels for each bubble.
- **labels** (array) - Optional - Array of labels for each bubble.

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#bubble-chart(
  (x: (25, 45, 60, 35, 70), y: (80, 65, 45, 55, 30), size: (100, 250, 180, 150, 300)),
  width: 350pt,
  height: 250pt,
  title: "Market Position Analysis",
  x-label: "Market Share (%)",
  y-label: "Growth Rate (%)",
  size-label: "Revenue",
  min-radius: 8pt,
  max-radius: 40pt,
  show-labels: true,
  labels: ("Product A", "Product B", "Product C", "Product D", "Product E"),
)
```
```

--------------------------------

### Load Bubble Chart Data

Source: https://context7.com/phiat/primaviz/llms.txt

Utilize `load-bubble` to structure JSON data for bubble charts. The input should be an array of objects, each containing 'x', 'y', and 'size' properties.

```typst
#import "@preview/primaviz:0.5.3": *

// Bubble data
#let bubble-data = load-bubble(json("bubbles.json"))
// Accepts: [{"x": 1, "y": 2, "size": 5}, ...]
#bubble-chart(bubble-data)
```

--------------------------------

### Render Pie and Donut Charts

Source: https://context7.com/phiat/primaviz/llms.txt

Use `pie-chart` for pie or donut charts. Customize size, title, legend, and percentage display. Set `donut: true` for a donut chart.

```typst
#import "@preview/primaviz:0.5.3": *

// Pie chart
#pie-chart(
  (
    labels: ("Chrome", "Safari", "Firefox", "Edge", "Other"),
    values: (65, 18, 8, 5, 4),
  ),
  size: 180pt,
  title: "Browser Market Share",
  show-legend: true,
  show-percentages: true,
)

// Donut chart variant
#pie-chart(
  (
    labels: ("Completed", "In Progress", "Pending"),
    values: (42, 28, 30),
  ),
  size: 150pt,
  title: "Task Status",
  donut: true,
  donut-ratio: 0.5,
)
```

--------------------------------

### Extend Primaviz Themes with Custom Keys

Source: https://github.com/phiat/primaviz/blob/main/README.md

Define custom theme keys within a Typst theme to extend the default system for your components. These custom keys are preserved and accessible.

```typst
#let my-theme = (
  palette: (red, blue, green),
  card-fill: rgb("#f5f5f5"),  // custom key — preserved and accessible
)
#show: with-theme.with(my-theme)
```

--------------------------------

### Sparkline

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a tiny inline line chart suitable for tables and running text, showing trends at a glance.

```APIDOC
## sparkline

### Description
Renders a tiny inline line chart suitable for tables and running text, showing trends at a glance.

### Parameters
- **values** (array) - Required - The data points for the sparkline.
- **width** (length) - Optional - The width of the sparkline.
- **height** (length) - Optional - The height of the sparkline.
- **fill-area** (bool) - Optional - Whether to fill the area under the line.
- **color** (color) - Optional - The color of the sparkline.

### Request Example (Inline in a table)
```typst
#import "@preview/primaviz:0.5.3": *

#table(
  columns: (auto, auto, auto),
  [*Metric*], [*Value*], [*Trend*],
  [Revenue], [$12.5M], [#sparkline((8, 10, 9, 12, 11, 14, 13, 15), width: 80pt, height: 20pt, fill-area: true)],
  [Users], [45K], [#sparkline((32, 35, 38, 42, 40, 45), width: 80pt, height: 20pt)],
  [Conversion], [3.2%], [#sparkline((2.8, 2.9, 3.0, 3.1, 3.0, 3.2), width: 80pt, height: 20pt, color: green)],
)
```
```

--------------------------------

### Render Bubble Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Visualizes data with x, y, and size dimensions. Features smart label deconfliction for readability. Define min/max radius for bubble scaling.

```typst
#import "@preview/primaviz:0.5.3": *

#bubble-chart(
  (
    x: (25, 45, 60, 35, 70),
    y: (80, 65, 45, 55, 30),
    size: (100, 250, 180, 150, 300),
  ),
  width: 350pt,
  height: 250pt,
  title: "Market Position Analysis",
  x-label: "Market Share (%)",
  y-label: "Growth Rate (%)",
  size-label: "Revenue",
  min-radius: 8pt,
  max-radius: 40pt,
  show-labels: true,
  labels: ("Product A", "Product B", "Product C", "Product D", "Product E")
)
```

--------------------------------

### Render Single-Series Line Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use `line-chart` for single-series line graphs. Options include points, value labels, area fill, and annotations like horizontal lines.

```typst
#import "@preview/primaviz:0.5.3": *

#line-chart(
  (
    labels: ("Jan", "Feb", "Mar", "Apr", "May", "Jun"),
    values: (42, 58, 53, 67, 72, 85),
  ),
  width: 350pt,
  height: 200pt,
  title: "Monthly Active Users (K)",
  show-points: true,
  show-values: false,
  line-width: 2pt,
  point-size: 5pt,
  x-label: "Month",
  y-label: "Users",
  annotations: (
    (type: "h-line", value: 60, color: red, dash: "dashed", label: "Target"),
  ),
)
```

--------------------------------

### Scale Chart Text and Spacing

Source: https://github.com/phiat/primaviz/blob/main/README.md

Adjusts font sizes and spacing proportionally by modifying `base-size` and `base-gap` within the theme. Smaller values result in a more compact chart.

```typst
#bar-chart(data, theme: (base-size: 10pt, base-gap: 8pt))  // larger text and spacing
#bar-chart(data, theme: (base-size: 5pt, base-gap: 3pt))   // compact
```

--------------------------------

### Create Sankey Flow Diagram

Source: https://context7.com/phiat/primaviz/llms.txt

Render a Sankey diagram with curved bands to visualize quantities flowing between nodes. Customize dimensions, title, and label visibility.

```typst
#import "@preview/primaviz:0.5.3": *

#sankey-chart(
  (
    nodes: ("Website", "Mobile App", "Signup", "Trial", "Paid", "Churned"),
    flows: (
      (from: 0, to: 2, value: 1000),  // Website -> Signup
      (from: 1, to: 2, value: 500),   // Mobile -> Signup
      (from: 2, to: 3, value: 800),   // Signup -> Trial
      (from: 3, to: 4, value: 400),   // Trial -> Paid
      (from: 3, to: 5, value: 300),   // Trial -> Churned
    ),
  ),
  width: 450pt,
  height: 300pt,
  title: "User Conversion Funnel",
  show-labels: true,
  show-values: true,
)
```

--------------------------------

### Render Circular Progress

Source: https://context7.com/phiat/primaviz/llms.txt

Displays a circular progress ring indicator with a percentage value in the center. Configure size, stroke width, and color.

```typst
#import "@preview/primaviz:0.5.3": *

#circular-progress(
  85,
  max-val: 100,
  size: 100pt,
  title: "Goal Progress",
  show-value: true,
  stroke-width: 10pt,
  color: rgb("#59a14f")
)
```

--------------------------------

### Progress Bar

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a horizontal progress bar with optional value label and rounded ends.

```APIDOC
## progress-bar

### Description
Renders a horizontal progress bar with optional value label and rounded ends.

### Parameters
- **value** (number) - Required - The current progress value.
- **max-val** (number) - Optional - The maximum value (defaults to 100).
- **width** (length) - Optional - The width of the progress bar.
- **height** (length) - Optional - The height of the progress bar.
- **title** (string) - Optional - The title of the progress bar.
- **show-value** (bool) - Optional - Whether to display the current value.
- **color** (color) - Optional - The color of the progress bar.
- **rounded** (bool) - Optional - Whether to use rounded ends for the bar.

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#progress-bar(
  72,
  max-val: 100,
  width: 250pt,
  height: 24pt,
  title: "Upload Progress",
  show-value: true,
  color: rgb("#4e79a7"),
  rounded: true,
)
```
```

--------------------------------

### Extract CSS Themes with TypeScript Script

Source: https://github.com/phiat/primaviz/blob/main/README.md

Utilize the TypeScript script for equivalent theme extraction from CSS. It can also extract additional semantic tokens into an 'all' field.

```bash
just extract-theme-ts src/index.css
```

```bash
just extract-theme-ts styles.css --name shadcn --format typst
```

--------------------------------

### Heatmap

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a grid heatmap with color-coded cells, automatic value labels, and a color scale legend.

```APIDOC
## heatmap

### Description
Renders a grid heatmap with color-coded cells, automatic value labels, and a color scale legend.

### Parameters
- **rows** (array) - Required - Labels for the rows.
- **cols** (array) - Required - Labels for the columns.
- **values** (array of arrays) - Required - A 2D array of values for the heatmap cells.
- **cell-size** (length) - Optional - The size of each cell in the heatmap.
- **title** (string) - Optional - The title of the heatmap.
- **show-values** (bool) - Optional - Whether to display the values in the cells.
- **palette** (string) - Optional - The color palette to use for the heatmap (e.g., "viridis", "heat").
- **show-legend** (bool) - Optional - Whether to display the color scale legend.

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#heatmap(
  (
    rows: ("Mon", "Tue", "Wed", "Thu", "Fri"),
    cols: ("9AM", "12PM", "3PM", "6PM"),
    values: (
      (45, 82, 67, 38),
      (52, 91, 73, 41),
      (48, 78, 85, 55),
      (61, 95, 88, 62),
      (35, 72, 58, 28),
    ),
  ),
  cell-size: 40pt,
  title: "Website Traffic by Day/Hour",
  show-values: true,
  palette: "viridis",
  show-legend: true,
)
```
```

--------------------------------

### Multi-Series Data Format for Primaviz

Source: https://github.com/phiat/primaviz/blob/main/README.md

Structure data for charts that display multiple data series over common labels.

```typst
(
  labels: ("Q1", "Q2", "Q3"),
  series: (
    (name: "Product A", values: (100, 120, 140)),
    (name: "Product B", values: (80, 90, 110)),
  ),
)
```

--------------------------------

### Render Gauge Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Displays a semicircular gauge with a needle. Supports default gradient or custom colored segments. Configure min/max values and labels.

```typst
#import "@preview/primaviz:0.5.3": *

// Default gradient gauge
#gauge-chart(
  75,
  min-val: 0,
  max-val: 100,
  size: 180pt,
  title: "CPU Usage",
  label: "percent",
  show-value: true
)

// Custom colored segments
#gauge-chart(
  68,
  min-val: 0,
  max-val: 100,
  size: 200pt,
  title: "Performance Score",
  segments: (
    (33, rgb("#e15759")),
    (66, rgb("#f28e2b")),
    (100, rgb("#59a14f")),
  )
)
```

--------------------------------

### Circular Progress

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a circular progress ring indicator with percentage display in the center.

```APIDOC
## circular-progress

### Description
Renders a circular progress ring indicator with percentage display in the center.

### Parameters
- **value** (number) - Required - The current progress value.
- **max-val** (number) - Optional - The maximum value (defaults to 100).
- **size** (length) - Optional - The size of the circular progress indicator.
- **title** (string) - Optional - The title of the indicator.
- **show-value** (bool) - Optional - Whether to display the current value in the center.
- **stroke-width** (length) - Optional - The width of the progress ring.
- **color** (color) - Optional - The color of the progress ring.

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#circular-progress(
  85,
  max-val: 100,
  size: 100pt,
  title: "Goal Progress",
  show-value: true,
  stroke-width: 10pt,
  color: rgb("#59a14f"),
)
```
```

--------------------------------

### Metric Card

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a dashboard KPI tile with a prominent value, label, delta indicator, and optional trend sparkline.

```APIDOC
## metric-card

### Description
Renders a dashboard KPI tile with a prominent value, label, delta indicator, and optional trend sparkline.

### Parameters
- **value** (number) - Required - The main value to display.
- **label** (string) - Required - The label for the metric.
- **delta** (number) - Optional - The change in value (e.g., percentage increase/decrease).
- **trend** (array) - Optional - Data points for a trend sparkline.
- **width** (length) - Optional - The width of the card.
- **format** (string) - Optional - Formatting for the value (e.g., "si" for SI units).
- **suffix** (string) - Optional - A suffix to append to the value.

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#metric-card(
  value: 12847,
  label: "Total Revenue",
  delta: 12.5,
  trend: (8200, 9100, 10300, 11200, 12100, 12847),
  width: 180pt,
  format: "si",
  suffix: " USD",
)
```
```

--------------------------------

### Render Stacked Bar Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use `stacked-bar-chart` to visualize individual and total values by stacking series vertically. Supports legends.

```typst
#import "@preview/primaviz:0.5.3": *

#stacked-bar-chart(
  (
    labels: ("2021", "2022", "2023", "2024"),
    series: (
      (name: "Mobile", values: (150, 180, 220, 280)),
      (name: "Desktop", values: (200, 190, 175, 160)),
      (name: "Tablet", values: (50, 65, 80, 95)),
    ),
  ),
  width: 350pt,
  height: 250pt,
  title: "Traffic by Device Type",
  show-legend: true,
)
```

--------------------------------

### Load Multi-Series Chart Data

Source: https://context7.com/phiat/primaviz/llms.txt

Employ `load-series` to prepare JSON data for grouped or stacked charts. It handles objects where keys represent series and nested objects represent data points.

```typst
#import "@preview/primaviz:0.5.3": *

// Multi-series data (for grouped/stacked charts)
#let series-data = load-series(json("quarterly.json"))
// Accepts: {"Q1": {"A": 10, "B": 20}, "Q2": {"A": 15, "B": 25}}
// Returns: (labels: ("Q1", "Q2"), series: ((name: "A", values: (10, 15)), ...))
#grouped-bar-chart(series-data)
```

--------------------------------

### Heatmap Data Format for Primaviz

Source: https://github.com/phiat/primaviz/blob/main/README.md

Define data for heatmap visualizations, specifying row and column labels along with their corresponding values.

```typst
(
  rows: ("Row1", "Row2", "Row3"),
  cols: ("Col1", "Col2", "Col3"),
  values: (
    (1, 2, 3),
    (4, 5, 6),
    (7, 8, 9),
  ),
)
```

--------------------------------

### Render Vertical Bar Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use `bar-chart` for vertical bar charts. Customize with width, height, title, labels, and themes. Supports showing values.

```typst
#import "@preview/primaviz:0.5.3": *

// Simple bar chart with inline data
#bar-chart(
  (
    labels: ("Q1", "Q2", "Q3", "Q4"),
    values: (120, 185, 145, 210),
  ),
  width: 300pt,
  height: 200pt,
  title: "Quarterly Revenue",
  show-values: true,
  x-label: "Quarter",
  y-label: "Revenue ($K)",
  theme: themes.minimal,
)
```

--------------------------------

### Render Scatter Plot

Source: https://context7.com/phiat/primaviz/llms.txt

Suitable for visualizing x-y data points. Customize labels, point size, and grid visibility for clarity. Ensure x and y arrays have the same length.

```typst
#import "@preview/primaviz:0.5.3": *

#scatter-plot(
  (
    x: (1, 2, 3, 4, 5, 6, 7, 8),
    y: (2.1, 4.3, 5.8, 8.2, 9.5, 12.1, 13.8, 16.2),
  ),
  width: 300pt,
  height: 200pt,
  title: "Price vs. Demand",
  x-label: "Price ($)",
  y-label: "Demand (units)",
  point-size: 6pt,
  show-grid: true
)
```

--------------------------------

### Scatter/Bubble Data Format for Primaviz

Source: https://github.com/phiat/primaviz/blob/main/README.md

Format data for scatter plots or bubble charts, including optional size values for bubbles.

```typst
(
  x: (1, 2, 3, 4, 5),
  y: (10, 25, 15, 30, 20),
  size: (5, 10, 8, 15, 12),  // for bubble chart
)
```

--------------------------------

### Radar Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a radar/spider chart for comparing multiple series across multiple axes. Ideal for skill assessments and multi-dimensional comparisons.

```APIDOC
## radar-chart

### Description
Renders a radar/spider chart for comparing multiple series across multiple axes, ideal for skill assessments and multi-dimensional comparisons.

### Parameters
- **labels** (tuple) - Required - Labels for the axes.
- **series** (tuple) - Required - Data series to plot, each with a name and values.
- **size** (length) - Optional - The overall size of the chart.
- **title** (string) - Optional - The title of the chart.
- **show-legend** (bool) - Optional - Whether to display the legend.
- **show-value-labels** (bool) - Optional - Whether to display value labels on the chart.
- **fill-opacity** (percent) - Optional - The opacity of the filled areas.

### Request Example
```typst
#import "@preview/primaviz:0.5.3": *

#radar-chart(
  (
    labels: ("Strength", "Speed", "Defense", "Magic", "Luck", "Charisma"),
    series: (
      (name: "Warrior", values: (18, 12, 16, 6, 10, 14)),
      (name: "Mage", values: (8, 10, 8, 18, 12, 15)),
    ),
  ),
  size: 250pt,
  title: "Character Stats Comparison",
  show-legend: true,
  show-value-labels: true,
  fill-opacity: 20%,
)
```
```

--------------------------------

### Load Scatter Plot Data

Source: https://context7.com/phiat/primaviz/llms.txt

Use `load-scatter` to format JSON data for scatter plots. It accepts arrays of objects with 'x' and 'y' properties or arrays of [x, y] pairs.

```typst
#import "@preview/primaviz:0.5.3": *

// Scatter data
#let scatter-data = load-scatter(json("points.json"))
// Accepts: [{"x": 1, "y": 2}, ...] or [[1, 2], [3, 4]]
#scatter-plot(scatter-data)
```

--------------------------------

### Render Horizontal Bar Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use `horizontal-bar-chart` for horizontal bars, suitable for long labels. Customize bar height and value visibility.

```typst
#import "@preview/primaviz:0.5.3": *

#horizontal-bar-chart(
  (
    labels: ("Engineering", "Marketing", "Sales", "Support", "Operations"),
    values: (45, 32, 28, 21, 15),
  ),
  width: 350pt,
  height: 200pt,
  title: "Department Headcount",
  bar-height: 0.7,
  show-values: true,
)
```

--------------------------------

### Render Radar Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Use for comparing multiple series across multiple axes, ideal for skill assessments. Ensure all necessary data points are provided for each series.

```typst
#import "@preview/primaviz:0.5.3": *

#radar-chart(
  (
    labels: ("Strength", "Speed", "Defense", "Magic", "Luck", "Charisma"),
    series: (
      (name: "Warrior", values: (18, 12, 16, 6, 10, 14)),
      (name: "Mage", values: (8, 10, 8, 18, 12, 15)),
    ),
  ),
  size: 250pt,
  title: "Character Stats Comparison",
  show-legend: true,
  show-value-labels: true,
  fill-opacity: 20%
)
```

--------------------------------

### Gauge Chart

Source: https://context7.com/phiat/primaviz/llms.txt

Renders a semicircular gauge/dial chart with a needle indicator, optional colored segments, and value display.

```APIDOC
## gauge-chart

### Description
Renders a semicircular gauge/dial chart with a needle indicator, optional colored segments, and value display.

### Parameters
- **value** (number) - Required - The current value to display on the gauge.
- **min-val** (number) - Optional - The minimum value of the gauge (defaults to 0).
- **max-val** (number) - Optional - The maximum value of the gauge (defaults to 100).
- **size** (length) - Optional - The size of the gauge.
- **title** (string) - Optional - The title of the gauge.
- **label** (string) - Optional - A label to display with the value (e.g., "percent").
- **show-value** (bool) - Optional - Whether to display the current value.
- **segments** (array of tuples) - Optional - Custom colored segments for the gauge, each tuple containing (end_value, color).

### Request Example (Default Gradient)
```typst
#import "@preview/primaviz:0.5.3": *

#gauge-chart(
  75,
  min-val: 0,
  max-val: 100,
  size: 180pt,
  title: "CPU Usage",
  label: "percent",
  show-value: true,
)
```

### Request Example (Custom Colored Segments)
```typst
#import "@preview/primaviz:0.5.3": *

#gauge-chart(
  68,
  min-val: 0,
  max-val: 100,
  size: 200pt,
  title: "Performance Score",
  segments: (
    (33, rgb("#e15759")),
    (66, rgb("#f28e2b")),
    (100, rgb("#59a14f")),
  ),
)
```
```