Merge pull request #2881 from evidence-dev/docs/using-queries-in-cust…

…om-components

feat: add documentation for component queries

sites/docs/pages/components/custom-components/component-queries.md

@@ -0,0 +1,161 @@
+# Component Queries
+
+Component queries allow you to run SQL queries in your component code.
+
+Component queries transform how we build data visualizations. Instead of passing data down through props from parent pages, components become self-contained units that can request exactly what they need. This independence makes components more reusable and easier to maintain, as all the logic for both fetching and displaying data lives in one place.
+
+## Static Queries
+
+Static queries are "static" because the SQL string they run cannot change throughout the component's lifecycle. They are defined once when your component is created, and are executed when `QueryLoad` is mounted.
+
+Here's how to create a component that fetches and displays information about tables in your database:
+
+```html title="components/TableList.svelte"
+<script>
+    import { buildQuery } from '@evidence-dev/component-utilities/buildQuery';
+    import { QueryLoad } from '@evidence-dev/core-components';
+
+    const query = buildQuery(
+        'SELECT * FROM information_schema.tables',
+    );
+</script>
+
+<QueryLoad data={query} let:loaded={tables}>
+    <svelte:fragment slot="skeleton" />
+
+    <ul>
+        {#each tables as table}
+            <li>{table.table_name}</li>
+        {/each}
+    </ul>
+</QueryLoad>
+```
+
+### The Query Loader
+
+The `QueryLoad` component manages the entire lifecycle of your query execution. It handles:
+- Executing your query against DuckDB
+- Managing loading states
+- Handling any errors that occur
+- Delivering results to your component
+
+```html
+<QueryLoad data={query} let:loaded={tableData}>
+    <svelte:fragment slot="skeleton" />
+    <!-- Your component content here -->
+</QueryLoad>
+```
+
+The `let:loaded` directive creates a new variable containing your query results. Using a descriptive name (like `tableData` or `salesMetrics`) makes your code more maintainable than the generic `loaded`.
+
+## Dynamic Queries
+
+For queries that change based on user input or component state, you need dynamic queries. This allows you to create interactive components.
+
+Here's an example that lets users control how many rows to display:
+
+```html title="components/DynamicTableList.svelte"
+&lt;script>
+    import { QueryLoad } from '@evidence-dev/core-components';
+    import { getQueryFunction } from '@evidence-dev/component-utilities/buildQuery';
+    import { Query } from '@evidence-dev/sdk/usql';
+
+    // This will hold our current query result
+    let query;
+
+    // Create a reactive query function
+    const queryFunction = Query.createReactive({
+        execFn: getQueryFunction(),
+        callback: v => query = v
+    });
+
+    // These values will control our query
+    let limit = 10;
+    let schemaName = 'public';
+
+    // This reactive statement runs whenever limit or schemaName change
+    $: queryFunction(`
+        SELECT * 
+        FROM information_schema.tables 
+        WHERE table_schema = '${schemaName}'
+        LIMIT ${limit}
+    `);
+</script>
+
+<div>
+    <label>
+        Rows to show:
+        <input type="number" bind:value={limit} min={0} />
+    </label>
+    <label>
+        Schema:
+        <input type="text" bind:value={schemaName} />
+    </label>
+</div>
+
+<QueryLoad data={query} let:loaded={tables}>
+    <svelte:fragment slot="skeleton" />
+    <ul>
+        {#each tables as table}
+            <li>{table.table_name}</li>
+        {/each}
+    </ul>
+</QueryLoad>
+```
+
+Let's understand how this works:
+
+### Query State Management
+
+1. First, we create a variable to hold our query result:
+   ```javascript
+   let query;
+   ```
+   This will be updated every time our query executes with new parameters.
+
+2. Next, we create a reactive query function:
+   ```javascript
+   const queryFunction = Query.createReactive({
+       execFn: getQueryFunction(),
+       callback: v => query = v
+   });
+   ```
+   This sets up an environment that can execute queries and update our component's state.
+
+3. Finally, we use Svelte's reactive declarations to run our query:
+   ```javascript
+   $: queryFunction(`SELECT * FROM ... LIMIT ${limit}`);
+   ```
+   The `$:` syntax tells Svelte to re-run this statement whenever `limit` changes, creating a connection between your component's state and your query.
+
+## Error Handling
+
+When working with queries, things can sometimes go wrong. Maybe a query is malformed, or perhaps it's trying to access a table that doesn't exist. The `QueryLoad` component helps you handle these situations gracefully through its error slot:
+
+```html
+<QueryLoad data={query} let:loaded={tables}>
+    <svelte:fragment slot="skeleton" />
+
+    <svelte:fragment slot="error" let:error>
+        <div class="text-red-600">
+            <h3 class="font-bold">Unable to load data</h3>
+            <p>{error.message}</p>
+            <p class="text-sm mt-2">
+                Please check your query and try again.
+            </p>
+        </div>
+    </svelte:fragment>
+
+    <ul>
+        {#each tables as table}
+            <li>{table.table_name}</li>
+        {/each}
+    </ul>
+</QueryLoad>
+```
+
+When a query fails, Evidence:
+1. Captures the error information
+2. Prevents the main content from rendering
+3. Makes the error details available through `let:error`
+4. Displays your error handling content

sites/docs/pages/components/custom-components/index.md

@@ -216,3 +216,7 @@ import formatTitle from '@evidence-dev/component-utilities/formatTitle';
 ```
 - `column`: name of column to be formatted
 - `columnFormat`: a format object for column being formatted (can be obtained from the `getColumnSummary` function)
+
+## Adding Queries
+
+Custom components can execute queries rather than requiring data to be passed to them. See [component queries](./component-queries) for details