{"id":50484737,"url":"https://github.com/unicolab/holysheet","last_synced_at":"2026-06-01T21:01:31.176Z","repository":{"id":359364416,"uuid":"1245431251","full_name":"UnicoLab/holysheet","owner":"UnicoLab","description":"HolySheet is a Python package that generates beautiful, self-contained, interactive HTML dashboards powered by React — without requiring the end user to install Node.js, npm, or any frontend tooling.","archived":false,"fork":false,"pushed_at":"2026-05-21T15:14:12.000Z","size":3568,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T23:07:34.423Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UnicoLab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T08:04:03.000Z","updated_at":"2026-05-21T15:22:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/UnicoLab/holysheet","commit_stats":null,"previous_names":["unicolab/holysheet"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/UnicoLab/holysheet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnicoLab%2Fholysheet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnicoLab%2Fholysheet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnicoLab%2Fholysheet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnicoLab%2Fholysheet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UnicoLab","download_url":"https://codeload.github.com/UnicoLab/holysheet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnicoLab%2Fholysheet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33793044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T21:01:29.432Z","updated_at":"2026-06-01T21:01:31.165Z","avatar_url":"https://github.com/UnicoLab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/holysheet_logo.png\" alt=\"HolySheet Mascot\" width=\"280\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e📊 HolySheet\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePython-first report compiler that turns raw data into stunning,\u003cbr\u003einteractive React dashboards — zero frontend knowledge required.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/holysheet_hero.png\" alt=\"HolySheet — Data to Dashboard\" width=\"680\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/holysheet\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/holysheet?color=3B82F6\u0026style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/holysheet\"\u003e\u003cimg alt=\"Downloads\" src=\"https://img.shields.io/pypi/dm/holysheet?color=F59E0B\u0026style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/holysheet\"\u003e\u003cimg alt=\"Python\" src=\"https://img.shields.io/pypi/pyversions/holysheet?color=8B5CF6\u0026style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/UnicoLab/holysheet/blob/main/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/UnicoLab/holysheet?color=10B981\u0026style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/UnicoLab/holysheet/actions\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/UnicoLab/holysheet/ci.yml?style=flat-square\u0026label=CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://unicolab.github.io/holysheet\"\u003e\u003cimg alt=\"Docs\" src=\"https://img.shields.io/badge/docs-mkdocs-blue?style=flat-square\u0026logo=materialformkdocs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://unicolab.github.io/holysheet\"\u003e📖 Documentation\u003c/a\u003e •\n  \u003ca href=\"#-see-it-in-action\"\u003eScreenshots\u003c/a\u003e •\n  \u003ca href=\"#-quickstart\"\u003eQuickstart\u003c/a\u003e •\n  \u003ca href=\"#-installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#-block-reference\"\u003eBlock Reference\u003c/a\u003e •\n  \u003ca href=\"#-examples\"\u003eExamples\u003c/a\u003e •\n  \u003ca href=\"#-architecture\"\u003eArchitecture\u003c/a\u003e •\n  \u003ca href=\"#-development\"\u003eDevelopment\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 📸 See It In Action\n\n\u003e **Don't take our word for it — see what HolySheet generates:**\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e🌙 Dark Theme\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_dark_theme.png\" alt=\"HolySheet Dark Theme Dashboard\" width=\"380\" /\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e☀️ Light Theme\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_light_theme.png\" alt=\"HolySheet Light Theme Dashboard\" width=\"380\" /\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e👔 Executive Theme\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_executive_theme.png\" alt=\"HolySheet Executive Theme Dashboard\" width=\"380\" /\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eAll dashboards above are generated from Python code — zero frontend knowledge required.\u003cbr/\u003eEach is a single, self-contained HTML file that opens in any browser.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e📊 Basic Report\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_basic_report.png\" alt=\"HolySheet Basic Report\" width=\"280\" /\u003e\u003cbr/\u003e\n\u003csub\u003eKPI cards + line chart · Light theme\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e💼 Sales Analytics\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_sales_dashboard.png\" alt=\"HolySheet Sales Dashboard\" width=\"280\" /\u003e\u003cbr/\u003e\n\u003csub\u003eTabbed charts + KPIs · Executive theme\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e🏢 Portfolio Report\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_portfolio_report.png\" alt=\"HolySheet Portfolio Report\" width=\"280\" /\u003e\u003cbr/\u003e\n\u003csub\u003eColumns layout + data table · Dark theme\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e🚀 Full Showcase\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_full_showcase.png\" alt=\"HolySheet Full Showcase\" width=\"280\" /\u003e\u003cbr/\u003e\n\u003csub\u003e37 blocks, all chart types · Dark theme\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## ✨ What is HolySheet?\n\n**HolySheet** generates stunning, self-contained, interactive HTML dashboards powered by **React** + **Apache ECharts** — without requiring Node.js, npm, or any frontend tooling.\n\n\u003e *Write your dashboard in Python. Get a gorgeous interactive report as a single HTML file.*  \n\u003e *No server. No dependencies. Just open it in a browser. Holy Sheet, that's easy!*\n\n### ⚡ Key Highlights\n\n- 🧱 **57 block types** — 18 charts, 6 metrics, 14 content/data, 8 layout, 9 interactive, AI insights + SQL\n- 🎨 **3 premium themes** — Dark, Light, and Executive with full design systems\n- 📦 **Single-file export** — One `.html` file (~1.5 MB) with everything embedded\n- 🐼 **Any data source** — Pandas, Polars, dicts, lists, Google Sheets\n- 🤖 **AI-powered insights** — OpenAI, Anthropic, Google Gemini integration\n- 🔐 **Enterprise features** — Password protection, expiring reports, PDF export\n- 🔧 **Developer tools** — CLI, hot-reload dev server, linting, report diff\n- 📱 **Responsive \u0026 PWA** — Works on mobile, supports offline mode\n\n```python\nfrom holysheet import Report, KPI, LineChart, DataTable\n\nreport = Report(title=\"Executive Portfolio Report\", theme=\"dark\")\n\nreport.add(KPI(label=\"Revenue\", value=1_250_000, unit=\"€\", delta=\"+12%\", status=\"positive\"))\nreport.add(LineChart(title=\"Revenue Trend\", data=revenue_df, x=\"date\", y=\"revenue\"))\nreport.add(DataTable(title=\"Projects\", data=projects_df))\n\nreport.export_html(\"report.html\")  # ← That's it. Open in any browser.\n```\n\n---\n\n## 🙏 Why HolySheet?\n\n| 😩 The Problem | 😇 The HolySheet Way |\n|---|---|\n| Dashboards require complex frontend setup | **Zero** frontend knowledge needed |\n| Reports need a running server | Self-contained HTML files — open anywhere |\n| Visualization libraries produce basic charts | Enterprise-grade React UI with interactive ECharts |\n| Sharing reports is painful | Single HTML file — email it, Slack it, embed it |\n| Python-to-dashboard tools look dated | Modern Material UI design with dark/light/executive themes |\n| Data wrangling across libraries | Native **Pandas**, **Polars**, dict, and list support |\n\n---\n\n## 🚀 Quickstart\n\n### 1. Install\n\n```bash\npip install holysheet\n```\n\n### 2. Build a dashboard\n\n```python\nfrom holysheet import Report, KPI, LineChart, BarChart, PieChart, DataTable, Section\n\nreport = Report(\n    title=\"Q4 Business Review\",\n    subtitle=\"Revenue \u0026 Operations Dashboard\",\n    theme=\"dark\",\n    author=\"Data Team\",\n)\n\n# KPI cards — they auto-arrange in a responsive grid\nreport.add(KPI(label=\"Total Revenue\", value=2_450_000, unit=\"€\", delta=\"+18%\", status=\"positive\"))\nreport.add(KPI(label=\"Active Clients\", value=142, delta=\"+12\", status=\"positive\"))\nreport.add(KPI(label=\"Churn Rate\", value=3.2, unit=\"%\", delta=\"-0.5%\", status=\"positive\"))\nreport.add(KPI(label=\"NPS Score\", value=72, delta=\"+5\", status=\"positive\"))\n\n# Charts — pass any DataFrame or list of dicts\nreport.add(LineChart(title=\"Monthly Revenue\", data=revenue_data, x=\"month\", y=\"revenue\"))\nreport.add(BarChart(title=\"Revenue by Region\", data=region_data, x=\"region\", y=\"revenue\"))\nreport.add(PieChart(title=\"Revenue Split\", data=split_data, name=\"category\", value=\"amount\"))\n\n# Searchable, paginated data table\nreport.add(DataTable(title=\"Top Clients\", data=clients_data, columns=[\"name\", \"revenue\", \"status\"]))\n\n# Export → a single portable HTML file\nreport.export_html(\"q4_review.html\")\n```\n\n### 3. Open \u0026 share\n\n```bash\nopen q4_review.html   # macOS\nxdg-open q4_review.html  # Linux\nstart q4_review.html  # Windows\n```\n\nThe HTML file is fully standalone — no server, no internet, no Node.js. Send it via email, upload to S3, embed in Confluence — it just works.\n\n---\n\n## 📦 Installation\n\n```bash\n# Core (zero extras)\npip install holysheet\n\n# With Pandas support\npip install holysheet[pandas]\n\n# With PDF export\npip install holysheet[pdf]\n\n# With AI insights (OpenAI / Anthropic / Google)\npip install holysheet[ai]\n\n# With cloud publishing (S3 / GCS)\npip install holysheet[cloud]\n\n# With Google Sheets data source\npip install holysheet[gsheets]\n\n# Everything\npip install holysheet[all]\n```\n\n**Requirements:**\n- 🐍 Python **3.11+**\n- 🚫 No Node.js required\n- 🚫 No frontend build step\n- 🚫 No running server\n\n**Core dependencies:** `pydantic v2` · `jinja2` · `orjson` · `loguru` · `click`\n\n---\n\n## 🧱 Block Reference\n\nHolySheet ships with **57 block types** organized into seven categories.\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003e🖼️ Block Preview — Charts \u0026 Data Tables\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_charts.png\" alt=\"HolySheet Chart Types\" width=\"520\" /\u003e\u003cbr/\u003e\n\u003csub\u003e18 chart types: line, bar, pie, radar, heatmap, funnel, and more\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_datatable.png\" alt=\"HolySheet Data Table\" width=\"520\" /\u003e\u003cbr/\u003e\n\u003csub\u003eInteractive tables with search, sort, pagination \u0026 conditional formatting\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003e🖼️ Block Preview — KPI Cards Across Themes\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_kpi_cards.png\" alt=\"HolySheet KPI Cards — Dark, Light, Executive\" width=\"720\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003eKPI cards automatically adapt to your chosen theme\u003c/sub\u003e\u003c/p\u003e\n\u003c/details\u003e\n\n### 📊 Charts (18)\n\n| Block | Description | Key Props |\n|---|---|---|\n| `LineChart` | Multi-series line chart | `data`, `x`, `y`, `series`, `annotations` |\n| `AreaChart` | Filled area chart | `data`, `x`, `y`, `series`, `annotations` |\n| `BarChart` | Grouped/stacked bar chart | `data`, `x`, `y`, `series`, `annotations` |\n| `PieChart` | Pie / donut chart | `data`, `name`, `value` |\n| `ScatterChart` | Scatter / bubble plot | `data`, `x`, `y`, `size`, `category` |\n| `RadarChart` | Radar / spider chart | `data`, `indicators` |\n| `GaugeChart` | Speedometer gauge | `value`, `min`, `max`, `thresholds` |\n| `FunnelChart` | Conversion funnel | `data`, `name`, `value` |\n| `TreemapChart` | Hierarchical treemap | `data`, `name`, `value`, `category` |\n| `HeatmapChart` | 2D heatmap with color gradient | `data`, `x`, `y`, `value` |\n| `CandlestickChart` | Financial OHLC chart | `data`, `x`, `open`, `close`, `low`, `high` |\n| `SankeyChart` | Flow / energy diagram | `nodes`, `links` |\n| `WaterfallChart` | Waterfall / bridge chart | `data`, `category`, `value` |\n| `BoxPlotChart` | Statistical box plot | `data`, `categories` |\n| `MapChart` | Geographical scatter | `data`, `lat`, `lng`, `value`, `name` |\n| `GanttChart` | Project timeline 🆕 | `tasks` `[{name, start, end, progress}]` |\n| `DAGChart` | Directed acyclic graph 🆕 | `nodes`, `edges`, `layout` |\n| `CorrelationMatrix` | Correlation heatmap 🆕 | `matrix`, `labels` |\n\n### 🧠 AI \u0026 Data Sources (3)\n\n| Block | Description | Key Props |\n|---|---|---|\n| `AIInsight` | LLM-powered data narrative 🆕 | `data`, `provider`, `prompt`, `api_key` |\n| `GoogleSheet` | Google Sheets data source 🆕 | `spreadsheet_id`, `sheet_name`, `range` |\n| `SqlBlock` | Client-side SQL queries 🆕 | `query`, `data`, `output` |\n\n### 📈 Metrics (6)\n\n| Block | Description | Key Props |\n|---|---|---|\n| `KPI` | Key metric card with delta + tooltips | `label`, `value`, `unit`, `delta`, `status`, `tooltip_detail` |\n| `Metric` | Compact inline metric | `label`, `value`, `unit`, `icon` |\n| `ProgressBar` | Progress indicator | `label`, `value`, `max`, `color` |\n| `StatComparison` | Side-by-side comparison | `title`, `items` |\n| `Scorecard` | Conditional color metric grid 🆕 | `data`, `columns`, `thresholds` |\n| `DataProfile` | Auto-EDA summary cards 🆕 | `columns` `[{name, dtype, count, ...}]` |\n\n### 📝 Content (12)\n\n| Block | Description | Key Props |\n|---|---|---|\n| `DataTable` | Searchable table + conditional formatting | `data`, `columns`, `formatting`, `downloadable` |\n| `Markdown` | Rich text content | `content` |\n| `CodeBlock` | Syntax-highlighted code | `code`, `language`, `title` |\n| `Image` | Image display | `src`, `alt`, `caption` |\n| `Alert` | Callout / notification | `severity`, `title`, `message` |\n| `Timeline` | Vertical event timeline | `events` `[{date, title, description}]` |\n| `Callout` | Styled quote / highlight | `content`, `author`, `variant` |\n| `JsonViewer` | Interactive JSON tree | `data`, `collapsed_depth` |\n| `UserCard` | Team member card | `name`, `role`, `avatar_url`, `stats` |\n| `StatusList` | Status indicators list | `items` `[{label, status, value}]` |\n| `InfoList` | Key-value pair display | `items` `[{key, value, icon}]` |\n| `Sparkline` | Tiny inline chart | `data`, `color`, `show_area` |\n| `NarrationBlock` | Voice narration (Web Speech API) 🆕 | `text`, `autoplay` |\n\n### 📐 Layout (8)\n\n| Block | Description | Key Props |\n|---|---|---|\n| `Section` | Group blocks with a heading | `title`, `description`, `children` |\n| `Columns` | Multi-column responsive grid | `children`, `widths` |\n| `Tabs` | Tabbed content panels | `tabs` (list of `{label, children}`) |\n| `Divider` | Visual separator line | `label`, `variant` |\n| `Accordion` | Collapsible content panels | `panels` (list of `{title, children}`) |\n| `Stepper` | Process / wizard steps | `steps` `[{label, description, status}]` |\n| `TagList` | Colored tag/badge chips | `tags` `[{label, color}]` |\n| `Compare` | Side-by-side comparison layout 🆕 | `left_label`, `right_label`, `left_children`, `right_children` |\n\n### 🎮 Interactive (9)\n\n| Block | Description | Key Props |\n|---|---|---|\n| `Slider` | Range slider input | `label`, `min`, `max`, `default_value` |\n| `NumberInput` | Numeric input field | `label`, `default_value`, `step` |\n| `Toggle` | On/off switch | `label`, `default_value` |\n| `Dropdown` | Select from options | `label`, `options`, `default_value` |\n| `TextInput` | Text / textarea input | `label`, `placeholder`, `multiline` |\n| `CheckboxGroup` | Multiple checkboxes | `label`, `options`, `default_values` |\n| `RadioGroup` | Single-select radio buttons | `label`, `options`, `default_value` |\n| `Embed` | Iframe embed | `url`, `height`, `aspect_ratio` |\n| `Video` | HTML5 video player | `src`, `poster`, `controls` |\n\n---\n\n## 🎨 Themes\n\nThree built-in themes ship out of the box:\n\n```python\nreport = Report(title=\"Report\", theme=\"dark\")       # 🌙 Deep dark, vibrant accents\nreport = Report(title=\"Report\", theme=\"light\")      # ☀️ Clean, professional, airy\nreport = Report(title=\"Report\", theme=\"executive\")  # 👔 Premium serif with rich greens\n```\n\nEach theme defines a complete design system: colors, typography (Inter / Georgia), spacing, shadows, and an 8-color chart palette.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e🌙 Dark\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_dark_theme.png\" alt=\"Dark Theme\" width=\"340\" /\u003e\u003cbr/\u003e\n\u003csub\u003eGlassmorphism cards, vibrant accents\u003cbr/\u003eIdeal for internal dashboards\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e☀️ Light\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_light_theme.png\" alt=\"Light Theme\" width=\"340\" /\u003e\u003cbr/\u003e\n\u003csub\u003eClean, professional, print-ready\u003cbr/\u003eIdeal for client-facing reports\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003cstrong\u003e👔 Executive\u003c/strong\u003e\u003cbr/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_executive_theme.png\" alt=\"Executive Theme\" width=\"340\" /\u003e\u003cbr/\u003e\n\u003csub\u003eGold accents, serif typography\u003cbr/\u003eIdeal for board presentations\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📚 Examples\n\n### Minimal Status Page\n\n```python\nfrom holysheet import Report, KPI, Markdown, Alert\n\nreport = Report(title=\"System Status\", theme=\"dark\")\n\nreport.add(Alert(severity=\"success\", title=\"All Systems Operational\", message=\"Last checked: 2 minutes ago\"))\nreport.add(KPI(label=\"Uptime\", value=99.97, unit=\"%\", status=\"positive\"))\nreport.add(KPI(label=\"Response Time\", value=142, unit=\"ms\", status=\"neutral\"))\nreport.add(KPI(label=\"Error Rate\", value=0.03, unit=\"%\", delta=\"-0.01%\", status=\"positive\"))\nreport.add(Markdown(content=\"Monitored endpoints: **API**, **Auth**, **CDN**, **Database**\"))\n\nreport.export_html(\"status.html\")\n```\n\n### Executive Dashboard with Sections \u0026 Columns\n\n```python\nfrom holysheet import Report, KPI, LineChart, BarChart, DataTable, Section, Columns, Markdown\n\nreport = Report(\n    title=\"AIFlow Executive Report\",\n    subtitle=\"Portfolio risk and delivery intelligence\",\n    theme=\"executive\",\n    author=\"Strategy Team\",\n)\n\n# Executive summary\nreport.add(Markdown(content=\"\"\"\n## Executive Summary\n\nPortfolio health remains strong with 42 active projects delivering on schedule.\nRisk-adjusted returns are trending positively, with a 12% improvement in delivery confidence.\n\"\"\"))\n\n# Note: Variables like risk_df, team_df, projects_df should be your DataFrames\n\n# KPI grid inside a section\nreport.add(Section(\n    title=\"Key Metrics\",\n    children=[\n        KPI(label=\"Active Projects\", value=42, delta=\"+3\", status=\"positive\"),\n        KPI(label=\"On-Track\", value=87, unit=\"%\", status=\"positive\"),\n        KPI(label=\"At-Risk\", value=5, status=\"negative\"),\n        KPI(label=\"Budget Utilization\", value=76, unit=\"%\", status=\"neutral\"),\n    ],\n))\n\n# Side-by-side charts\nreport.add(Columns(children=[\n    LineChart(title=\"Risk Score Trend\", data=risk_df, x=\"date\", y=\"score\"),\n    BarChart(title=\"Delivery by Team\", data=team_df, x=\"team\", y=\"delivered\"),\n]))\n\n# Detailed data\nreport.add(DataTable(\n    title=\"Project Details\",\n    data=projects_df,\n    columns=[\"project\", \"owner\", \"risk\", \"status\", \"completion\"],\n))\n\nreport.export_html(\"executive_report.html\")\n```\n\n### Multi-Chart Analytics with Tabs\n\n```python\nfrom holysheet import Report, Tabs, LineChart, BarChart, PieChart, FunnelChart\n\nreport = Report(title=\"Sales Analytics\", theme=\"dark\")\n\nreport.add(Tabs(tabs=[\n    {\n        \"label\": \"📈 Trends\",\n        \"children\": [\n            LineChart(title=\"Monthly Sales\", data=sales_df, x=\"month\", y=\"total\"),\n            LineChart(title=\"Customer Growth\", data=growth_df, x=\"month\", y=\"customers\"),\n        ],\n    },\n    {\n        \"label\": \"📊 Breakdown\",\n        \"children\": [\n            BarChart(title=\"Sales by Region\", data=region_df, x=\"region\", y=\"sales\"),\n            PieChart(title=\"Product Mix\", data=product_df, name=\"product\", value=\"revenue\"),\n        ],\n    },\n    {\n        \"label\": \"🔄 Pipeline\",\n        \"children\": [\n            FunnelChart(title=\"Sales Funnel\", data=funnel_df, name=\"stage\", value=\"count\"),\n        ],\n    },\n]))\n\nreport.export_html(\"sales_analytics.html\")\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🖼️ Example Output — Sales Dashboard (Executive Theme)\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/UnicoLab/holysheet/main/assets/screenshot_executive_theme.png\" alt=\"Sales Dashboard Output\" width=\"720\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003eGenerated by \u003ccode\u003eexamples/sales_dashboard.py\u003c/code\u003e — a single self-contained HTML file\u003c/sub\u003e\u003c/p\u003e\n\u003c/details\u003e\n\n\u003e 💡 **More examples** in the [`examples/`](examples/) directory — including a full showcase with every block type.\n\n---\n\n## 📤 Export Modes\n\n### Standalone HTML *(default)*\n\n```python\nreport.export_html(\"report.html\")\n```\n\nGenerates a **single, self-contained HTML file** (~1.5 MB) with embedded React, CSS, and data. Zero external dependencies. Open directly in any browser.\n\n### Folder Export\n\n```python\nreport.export_folder(\"dist/\")\n```\n\nGenerates a deployable folder structure:\n\n```\ndist/\n  index.html       ← Entry point\n  assets/\n    app.js         ← React bundle\n    app.css        ← Styles\n  report.json      ← Dashboard spec\n```\n\nIdeal for hosting on a web server, S3, or CDN.\n\n### PDF Export\n\n```python\nreport.export_pdf(\"report.pdf\", landscape=True, margin=\"0.5in\")\n```\n\nRequires Playwright (`pip install holysheet[pdf]`) or Chrome/Chromium.\n\n### JSON Export\n\n```python\nreport.export_json(\"report.json\")\n```\n\nExports just the dashboard specification as JSON. Useful for debugging, version control, or feeding into external rendering pipelines.\n\n---\n\n## 🗄️ Data Formats\n\nHolySheet auto-detects and converts data from multiple formats:\n\n```python\n# ✅ List of dicts\ndata = [{\"name\": \"Alice\", \"score\": 95}, {\"name\": \"Bob\", \"score\": 87}]\n\n# ✅ Dict of lists\ndata = {\"name\": [\"Alice\", \"Bob\"], \"score\": [95, 87]}\n\n# ✅ Pandas DataFrame\nimport pandas as pd\ndata = pd.DataFrame({\"name\": [\"Alice\", \"Bob\"], \"score\": [95, 87]})\n\n# ✅ Polars DataFrame\nimport polars as pl\ndata = pl.DataFrame({\"name\": [\"Alice\", \"Bob\"], \"score\": [95, 87]})\n```\n\nAll formats are normalized to records internally via `holysheet.data.to_records()`.\n\n---\n\n## 💻 CLI\n\n```bash\n# Validate a report spec\nholysheet validate report.json\n\n# Serve a report locally (opens browser)\nholysheet serve report.json\n\n# Hot-reload dev server — auto-refreshes on Python script changes\nholysheet dev my_report.py --port 8000\n\n# Lint a report for best practices\nholysheet lint my_report.py --strict\n\n# Compare two report versions\nholysheet diff old_report.json new_report.json\n\n# Show version\nholysheet version\n\n# Publish to S3 or Google Cloud Storage\nholysheet publish report.html -t s3://my-bucket/reports/q4.html --public\nholysheet publish report.html -t gs://my-bucket/reports/q4.html\n```\n\n---\n\n## 🔥 Advanced Features\n\n### Custom Themes\n\n```python\nfrom holysheet import Report, Theme\n\nbrand = Theme(name=\"acme\", primary=\"#FF6B00\", background=\"#0A0A0F\", font=\"Satoshi\")\nreport = Report(title=\"Acme Report\", theme=brand)\n```\n\n### Multi-Page Reports\n\n```python\nreport.add_page(\"Overview\", [KPI(label=\"Revenue\", value=\"$1.2M\")])\nreport.add_page(\"Details\", [DataTable(title=\"Breakdown\", data=df)])\n```\n\n### Chart Annotations\n\n```python\nreport.add(LineChart(\n    title=\"Revenue\", data=df, x=\"month\", y=\"revenue\",\n    annotations=[{\"x\": \"Mar\", \"text\": \"Product Launch\", \"color\": \"#22d3ee\"}]\n))\n```\n\n### Global Filters\n\n```python\nreport.add_filter(\"region\", type=\"dropdown\", options=[\"NA\", \"EU\", \"APAC\"])\n```\n\n### Jupyter Integration\n\n```python\nreport.show()  # Renders inline in Jupyter notebook\n```\n\n### Password Protection \u0026 Expiry\n\n```python\nreport.export_html(\"secure.html\", password=\"s3cret\")  # AES-256 encrypted\nReport(title=\"Temp\", expires=\"2025-12-31\")  # Auto-expires\n```\n\n### Report Templates\n\n```python\nfrom holysheet.templates import SalesDashboard, ExecutiveSummary, OpsMonitor\n\nblocks = SalesDashboard(data={\"kpis\": {\"revenue\": \"$1.2M\", \"deals_won\": 42}})\n```\n\n### Anomaly Detection\n\n```python\nreport.add(LineChart(\n    title=\"Server Latency\", data=metrics, x=\"time\", y=\"latency_ms\",\n    anomaly_detection=True,  # Auto-detect and annotate outliers\n))\n```\n\n### AI-Powered Insights\n\n```python\nfrom holysheet import AIInsight\nreport.add(AIInsight(title=\"Key Findings\", data=df, provider=\"openai\"))\n```\n\n### SQL Block\n\n```python\nfrom holysheet import SqlBlock\nreport.add(SqlBlock(\n    query=\"SELECT region, SUM(revenue) FROM data GROUP BY region\",\n    data=sales_df,\n))\n```\n\n### Voice Narration\n\n```python\nfrom holysheet import NarrationBlock\nreport.add(NarrationBlock(text=report.auto_narrate()))\n```\n\n---\n\n## 🏗️ Architecture\n\n```\nPython API  →  Pydantic v2 Schema  →  JSON Spec  →  React Renderer  →  HTML Dashboard\n```\n\nHolySheet operates in two distinct phases:\n\n### 🔧 Build Time *(Python — your machine)*\n\n1. You define blocks using the Python API\n2. HolySheet validates everything with **Pydantic v2** models\n3. Generates a versioned JSON dashboard specification\n4. Injects the spec into a **prebuilt React application**\n5. Exports a self-contained HTML file via **Jinja2** templates\n\n### 🌐 Runtime *(Browser — any machine)*\n\n1. Browser opens the HTML file (no server needed)\n2. React reads the embedded dashboard spec from `\u003cscript id=\"report-data\"\u003e`\n3. Renders each block through a **component registry** (`type` → React component)\n4. Charts become interactive via **Apache ECharts**\n5. Tables support real-time search and pagination\n\n\u003e **The key insight:** The React app is **prebuilt and bundled inside the Python package**. End users never need Node.js, npm, or any frontend tooling.\n\n### Project Structure\n\n```\nHolySheet/\n  src/holysheet/           # Python package\n    __init__.py            #   Public API (20 block types + Report)\n    blocks.py              #   Pydantic v2 block models\n    schema.py              #   Report schema model\n    report.py              #   Main Report class + export methods\n    data.py                #   Data normalization (pandas/polars/dict/list)\n    exporters.py           #   HTML / folder / JSON exporters\n    themes.py              #   Theme system (light / dark / executive)\n    exceptions.py          #   Custom exception hierarchy\n    cli.py                 #   Click-based CLI (validate, serve, version)\n    renderer/              #   Prebuilt React assets (JS + CSS)\n    templates/             #   Jinja2 HTML templates\n\n  frontend/                # React source (development only)\n    src/\n      components/          #   React block components\n      theme.ts             #   MUI theme definitions\n      registry.tsx         #   Block type → component mapping\n      types.ts             #   TypeScript interfaces\n\n  tests/                   # Python test suite\n  examples/                # Example scripts\n```\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Python **3.11+**\n- Node.js **18+** *(frontend development only)*\n- Make\n\n### Setup\n\n```bash\ngit clone https://github.com/UnicoLab/HolySheet.git\ncd HolySheet\n\n# Full development setup (frontend + Python)\nmake dev\n\n# Or step by step:\nmake frontend-install   # Install frontend npm dependencies\nmake frontend-build     # Build React app → src/holysheet/renderer/\nmake install            # Install Python package in editable mode\n```\n\n### Common Commands\n\n```bash\nmake test              # Run Python test suite\nmake lint              # Lint with ruff\nmake typecheck         # Type-check with mypy (strict mode)\nmake format            # Auto-format with ruff\nmake build             # Build distributable wheel + sdist\nmake clean             # Clean all build artifacts\n```\n\n### Releases\n\nHolySheet uses [python-semantic-release](https://github.com/python-semantic-release/python-semantic-release) with conventional commits:\n\n| Prefix | Effect |\n|---|---|\n| `feat:` | Minor version bump |\n| `fix:` / `perf:` | Patch version bump |\n| `BREAKING CHANGE:` | Major version bump |\n\n---\n\n## 🗺️ Roadmap\n\n- [x] 📊 Advanced chart types (Sankey, Gantt, DAG, Correlation Matrix)\n- [x] 🔍 Interactive filters and global filter bar\n- [x] 📑 Multi-page tabbed report navigation\n- [x] 🎨 Custom theme API + enterprise branding\n- [x] 🔐 Password-protected \u0026 expiring reports\n- [x] 📥 CSV download buttons on tables \u0026 charts\n- [x] 📓 Jupyter notebook integration\n- [x] 🎯 Chart annotations (vertical lines, point markers)\n- [x] 📽️ Presentation mode (sections as slides)\n- [x] 🌗 Dark/Light theme toggle in viewer\n- [x] 🏗️ Report templates (SalesDashboard, ExecutiveSummary, OpsMonitor)\n- [x] 🔧 Hot-reload dev server + report linting + report diff CLI\n- [x] 🤖 AI narrative blocks (AIInsight with OpenAI / Anthropic / Google)\n- [x] 📄 PDF export (Playwright / Chrome)\n- [x] 🗄️ SQL Block (client-side query engine)\n- [x] 🔊 Voice narration (Web Speech API)\n- [x] 📈 Anomaly detection on charts (IQR + MAD)\n- [x] ☁️ Cloud publish CLI (S3 / GCS)\n- [x] 📊 Google Sheets data source\n- [x] 🔄 Cross-block reactive filtering\n- [x] 📜 Virtual scrolling for large tables\n- [x] 🗺️ Report navigator (minimap)\n- [x] 📱 PWA mode + responsive layouts\n- [ ] 📊 PowerPoint export\n- [ ] 🧩 Custom React component injection\n- [ ] 💬 Local chatbot over report data\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. **Fork** the repository\n2. **Create** a feature branch: `git checkout -b feat/amazing-feature`\n3. **Write** your changes with tests\n4. **Check** everything passes: `make lint \u0026\u0026 make typecheck \u0026\u0026 make test`\n5. **Commit** with [conventional commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, etc.\n6. **Open** a Pull Request\n\nSee the [Contributing Guide](CONTRIBUTING.md) for detailed instructions.\n\n---\n\n## 📄 License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with ❤️ by \u003ca href=\"https://github.com/UnicoLab\"\u003eUnicoLab\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eHoly Sheet, that's a beautiful dashboard! 🙌\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\n    \u003ca href=\"https://pypi.org/project/holysheet\"\u003ePyPI\u003c/a\u003e ·\n    \u003ca href=\"https://unicolab.github.io/holysheet\"\u003eDocumentation\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/UnicoLab/holysheet/issues\"\u003eIssues\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/UnicoLab/holysheet/discussions\"\u003eDiscussions\u003c/a\u003e\n  \u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funicolab%2Fholysheet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funicolab%2Fholysheet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funicolab%2Fholysheet/lists"}