@graphenedata/cli 0.0.1

package/dist/docs/data_apps/components/ui/link.md

@@ -0,0 +1,40 @@
+---
+title: Link
+description: Add an inline link into your markdown
+---
+
+> **Note:** You can also use [markdown syntax for links](/reference/markdown#links). This component is useful when you need to customize the behavior or styling of the link (e.g., opening in new tab vs. current tab)
+
+Use the `Link` component to add styled and accessible links to your markdown pages. This component allows you to control the destination URL, link text, and whether it opens in a new tab.
+
+## Default usage
+
+**Example:**
+
+```markdown
+<Link 
+    url="https://github.com/evidence-dev/evidence"
+    label="Visit Example"
+/>
+```
+
+### Open in a new tab
+
+**Example:**
+
+```markdown
+<Link 
+    url="https://github.com/evidence-dev/evidence"
+    label="Visit Example"
+    newTab=true
+/>
+```
+
+## Options
+
+| Property | Description | Required | Options | Default |
+|----------|-------------|----------|---------|---------|
+| url | The destination URL of the link. It can accept either a full external link (e.g. `https://google.com`) or link to another page within your evidence app (e.g. `/sales/performance`). | true | string | - |
+| label | The text displayed for the link. | false | string | Click here |
+| newTab | Whether the link should open in a new tab | false | true, false | false |
+| class | Pass custom classes to style the link. Supports [Tailwind classes](https://tailwindcss.com). | false | string | - |

package/dist/docs/data_apps/components/ui/modal.md

@@ -0,0 +1,57 @@
+---
+title: Modal
+description: Display a pop-up dialog when a button is clicked.
+---
+
+**Example:**
+
+```markdown
+<Modal title="Title" buttonText='Open Modal'> 
+
+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.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
+
+</Modal>
+```
+
+## Styling
+
+Modals support markdown in the body, but you need to leave whitespace between the text and the modal tags. 
+
+**Example:**
+
+```markdown
+<Modal title="Title" buttonText='Open Modal'>
+
+**bold** and _italic_ text is supported.
+
+</Modal>
+```
+
+## Including Components
+
+
+You can include components inside a Modal, like charts or tables:
+
+**Example:**
+
+```svelte
+<Modal title='Chart Example' buttonText='Click to See Chart'>
+    <LineChart
+        data="orders_by_month"
+        x=order_month
+        y=sales_usd0k
+    />
+</Modal>
+```
+
+## Options
+
+| Property | Description | Required | Options | Default |
+|----------|-------------|----------|---------|---------|
+| buttonText | The text displayed on the button that triggers the modal. | true | string | - |
+| title | The title of the modal. Visible at the top of the modal when it is open | false | string | - |
+| open | A boolean value that determines whether the modal is closed by default. | false | true, false | false |

package/dist/docs/data_apps/components/ui/note.md

@@ -0,0 +1,32 @@
+---
+title: Note
+description: Display smaller text for definitions, notes, and footnotes
+---
+
+Use the `Note` component to display small, styled text for additional context or information
+
+## Default usage
+
+**Example:**
+
+```markdown
+<Note>
+    This is a note for additional context.
+</Note>
+```
+
+### Custom styling
+
+**Example:**
+
+```markdown
+<Note class="text-negative">
+    This is a custom-styled note.
+</Note>
+```
+
+## Options
+
+| Property | Description | Options |
+|----------|-------------|---------|
+| class | Pass custom classes to style the note. Supports [Tailwind classes](https://tailwindcss.com). | string |

package/dist/docs/data_apps/components/ui/print-format-components.md

@@ -0,0 +1,85 @@
+---
+title: Print Format Components
+description: Format your report content for PDF export or printing.
+---
+
+These components can be used to format your report content for PDF export or printing.
+
+## LineBreak
+Inserts a line break on the page (in the UI as well as on print).
+
+This can be helpful when working with many input components (filters, dropdowns, etc.)
+
+```html
+Text on original line <LineBreak/> Text on new line
+```
+
+### Options
+
+| Name | Description | Required | Options | Default |
+|------|-------------|----------|---------|---------|
+| lines | Number of line breaks to insert | false | number | 1 |
+
+## PageBreak
+On print, inserts a page break - pushing the next content onto the start of a new page.
+
+```html
+The purple line chart in this section will print on a new page.
+
+<LineChart 
+    data="orders_by_month" 
+    x=month
+    y=sales_usd0k 
+/>
+
+<PageBreak/>
+
+<LineChart 
+    data="orders_by_month" 
+    x=month
+    y=sales_usd0k 
+    lineColor=purple
+/>
+
+```
+
+## PrintGroup
+- Combines content to be printed on the same page if possible
+- Offers a `hidden` prop. If `true`, the content within the PrintGroup will not be printed
+
+```html
+<PrintGroup>
+
+    The 2 heatmaps below will be printed on the same page if possible
+
+    <Heatmap data="item_channel" x=channel y=item value=orders/>
+    <Heatmap data="item_channel" x=channel y=item value=orders/>
+</PrintGroup>
+```
+
+### `hidden=true`
+
+```html
+The purple line chart will be hidden on print
+
+<LineChart 
+    data="orders_by_month" 
+    x=month
+    y=sales_usd0k 
+/>
+
+<PrintGroup hidden=true>
+    <LineChart 
+        data="orders_by_month" 
+        x=month
+        y=sales_usd0k 
+        lineColor=purple
+    />
+</PrintGroup>
+```
+
+### Options
+
+| Name | Description | Required | Options | Default |
+|------|-------------|----------|---------|---------|
+| hidden | If true, the content within the PrintGroup will not be printed | false | ['true', 'false'] | 'false' |

package/dist/docs/data_apps/components/ui/tabs.md

@@ -0,0 +1,122 @@
+---
+title: Tabs
+description: Organize content across multiple panes.
+---
+
+Use Tabs to organize content across multiple panes.
+
+**Example:**
+
+```markdown
+<Tabs>
+    <Tab label="First Tab">
+        Content of the First Tab
+
+        You can use **markdown** here too!
+    </Tab>
+    <Tab label="Second Tab">
+        Content of the Second Tab
+
+        Here's a [link](https://www.google.com)
+    </Tab>
+</Tabs>
+```
+
+## Examples
+
+### Full Width
+
+**Example:**
+
+```markdown
+<Tabs fullWidth=true>
+    <Tab label="First Tab">
+        Content of the First Tab
+    </Tab>
+    <Tab label="Second Tab">
+        Content of the Second Tab
+    </Tab>
+</Tabs>
+```
+
+### Theme Color
+
+**Example:**
+
+```markdown
+<Tabs color=primary>
+    <Tab label="Primary Tabs">
+        Content of the First Tab
+    </Tab>
+    <Tab label="Second Tab">
+        Content of the Second Tab
+    </Tab>
+</Tabs>
+```
+
+### Custom Color
+
+**Example:**
+
+```markdown
+<Tabs color=#ff0000>
+    <Tab label="Red Tabs">
+        Content of the First Tab
+    </Tab>
+    <Tab label="Second Tab">
+        Content of the Second Tab
+    </Tab>
+</Tabs>
+```
+
+### Background Color
+
+**Example:**
+
+```markdown
+<Tabs background=true>
+    <Tab label="First Tab">
+        Content of the First Tab
+    </Tab>
+    <Tab label="Second Tab">
+        Content of the Second Tab
+    </Tab>
+</Tabs>
+```
+
+### Persist Selected Tab to URL
+
+**Example:**
+
+```markdown
+<Tabs id="example-tab">
+    <Tab label="One">
+        Click Second id Tab and notice the the url updates!
+    </Tab>
+    <Tab label="Two">
+        Refresh the page and the tab you selected persists!
+    </Tab>
+</Tabs>
+```
+
+# Tabs
+
+## Options
+
+| Property | Description | Options | Default |
+|----------|-------------|---------|---------|
+| id | Unique Id for this set of tabs. When set, the selected tab is included in the URL so it can be shared. | string | - |
+| color | Color for the active tab. Accepts theme tokens | Any valid hex, rgb, or hsl string | base-content |
+| fullWidth | Tabs take up full width of page | true, false | false |
+| background | Include background color on active tab. Color is automatically determined based on `color` prop | true, false | false |
+
+# Tab
+
+## Options
+
+| Property | Description | Required | Options | Default |
+|----------|-------------|----------|---------|---------|
+| label | Label for the tab | true | string | - |
+| id | Unique Id for this tab. Only needed if 2 tabs have the same label (not recommended). | false | string | - |
+| printShowAll | On print/PDF, the Tabs will repeat to show all content by default. Turn this off to leave the component collapsed in print. | false | true, false | true |
+| description | Adds an info icon with description tooltip on hover | false | string | - |

package/dist/docs/graphene.md

@@ -0,0 +1,129 @@
+# How to develop in Graphene
+
+Graphene is a framework for building semantic layers and data visualizations in code. Graphene projects are comprised of:
+- .gsql files that define semantics-enriched tables (aka semantic models)
+- .md files that define data apps (dashboards)
+
+Graphene also has a CLI that lets you check syntax, run queries, serve data apps, and more.
+
+## Graphene SQL (GSQL)
+
+### Tables
+Tables have to be declared first before they can be queried. A table in Graphene has the added concept of _semantics_. Semantics are stored expressions and join relationships associated with a table that `select` queries can leverage. This allows query logic to be centralized, reusable, and more easily governed.
+
+Here's an example:
+
+```gsql
+table orders (
+  id BIGINT primary_key,
+  user_id BIGINT,
+  created_at DATETIME,
+  amount FLOAT, -- paid by customer #units=usd
+  cost FLOAT, -- cost of materials #units=usd
+
+  join_one users on user_id = users.id,
+
+  sum(amount) as revenue,
+  sum(amount - cost) as profit,
+  profit / revenue as profit_margin
+);
+
+table users (
+  id BIGINT primary_key,
+  name VARCHAR,
+  email VARCHAR,
+  age INTEGER,
+
+  join_many orders on id = orders.user_id
+);
+```
+
+Syntax notes
+- `table foo (...)` defines a Graphene table based on the database table `foo`. 
+- The allowed join types are `join_one` and `join_many`. All joins are left outer joins. There is no inner, right, or cross join.
+- `join_one` is used if there are many rows in the **left** table for each row in the **right** table.
+- `join_many` is used if there are many rows in the **right** table for each row in the **left** table.
+- Join names within a table must be unique. Polymorphic relationships (eg., where there are multiple relationships between the same two tables on different keys) are allowed but must be aliased eg. `join_one users as owner on user_id = owner.id` and `join_one users as viewer on user_id = viewer.id`.
+- Comments in tables can provide descriptions as well as metadata (denoted by `#` inside the comment).
+
+Best practices
+- For a given table, only model joins that are directly on that table. Graphene will automatically traverse multi-hop joins when it compiles the collective table space.
+- A join between two tables should be modeled in both the respective `table` statements. This may seem redundant but it offers more flexibility for queries to choose which table to set in the `from` (remember that direction matters since all joins are left joins).
+
+### Queries
+Graphene tables can be queried using `select` statements. Here are some example queries on the tables above:
+
+```
+-- top 10 customers by profit
+from orders select
+  users.name, -- notice how we can access the joined table without a join here
+  profit -- this expands into the stored expression defined in the table
+order by 2 desc
+limit 10
+```
+
+```
+-- average age of customers over time
+select
+  month(date),
+  average(users.age), -- in normal SQL this would fan-out in the join; in Graphene it smartly de-duplicates the fan-out when computing aggregates
+from orders 
+```
+
+Syntax notes
+- Columns and stored expressions from joined tables can be accessed with the dot operator, eg. `users.age` in the example above. Multiple join hops can be traversed with multiple dots, eg. `users.countries.country_code`.
+- `join_one` and `join_many` work here, too. This is useful if the join you need has not been modeled already.
+- The `from`, `select`, `group by`, and `where` clauses can be written in any order.
+- Expressions in `group by` are implicitly selected, so `from orders select avg(amount) group by user_id` is valid.
+- `group by all` is implied if aggregate and scalar expressions are both present in the `select`. It can be omitted and the query will still effectively execute the `group by all`.
+- `count` is a reserved word. Do not alias your columns as `count`.
+
+
+## Graphene viz (.md)
+Graphene data apps are written in Markdown with components. Markdown files can contain named GSQL queries in code fences that components can then refer to. Those queries can use any tables defined in .gsql files.
+
+````markdown
+  # Order analysis
+  Looking at our order breakdowns.
+
+  ```sql orders_by_month
+    from orders select date_trunc(created_at, month) as month, count(*) as num_orders, profit
+  ```
+
+  <Row>
+    <LineChart data="orders_by_month" x="month" y="num_orders" title="Orders by Month" />
+    <LineChart data="orders" x="date_trunc(created_at, month)" y="profit" title="Profit by Month, USD" />
+  </Row>
+````
+
+Note that components can also directly refer to Graphene tables in their `data` property; it is not always necessary to prepare data in a code-fenced query. Properties that take column references can also take whole expressions, as shown in the second line chart from the example above.
+
+### Components
+The following components are available:
+- [BarChart](./data_apps/components/charts/bar-chart.md)
+- [LineChart](./data_apps/components/charts/line-chart.md)
+- [AreaChart](./data_apps/components/charts/area-chart.md)
+- PieChart - takes a `category` and `value` attribute
+- Row - evenly distributes its children in a row
+- [DateRange](./data_apps/components/inputs/date-range.md)
+- [BigValue](./data_apps/components/data/big-value.md)
+- [Table](./data_apps/components/data/table.md)
+- [TextInput](./data_apps/components/inputs/text-input.md)
+
+## Using the Graphene CLI
+These are the available commands:
+- `npm run cli check` - Checks the syntax for the entire Graphene project.
+- `npm run cli compile "<GSQL>"` - Shows how GSQL is translated into the underlying database SQL.
+- `npm run cli run "<GSQL>"` - Runs a GSQL query. The tables and semantics defined in all .gsql files in the project are available for the query to use.
+- `npm run cli serve` - Starts (or restarts) the dev server, which allows the user to view their Graphene app on localhost.
+- `npm run cli view <mdPath>` - Captures a screenshot of a given .md file, along with any errors encountered.
+
+## AGENT INSTRUCTIONS
+Follow these guidelines when working in a Graphene project.
+- Before writing any GSQL queries, run them in the CLI first to make sure that the results make sense.
+- Do not redefine joins or expressions in a GSQL query that already exist in a semantic model. For example, if profit has already been defined as the stored expression `sum(revenue - cost) as profit` on the table `orders`, you can simply use it in a downstream query as `select profit from orders`.
+- Because all joins in Graphene are left outer joins, be mindful about your `from` table selection.
+- When adding a component to a .md file, read the associated documentation page first in /docs/data_apps/components so you understand all the available configurations.
+- Do not try to search the web for Graphene-specific info; you will not find anything. All the documentation is in /docs.
+- If you write to a .gsql file, run a syntax check with `npm run cli check`.
+- If you write to a .md file, run a syntax check with `npm run cli check`. Once there are no syntax errors, do a visual check by running `npm run cli view <mdPath>` and looking at the .png it generates.