@shotleybuilder/svelte-gridlite-kit 0.3.1 → 0.4.0

package/README.md

@@ -110,7 +110,7 @@ Focused, single-feature demo pages in `src/routes/examples/`:
 | `/examples/filtering` | FilterBar + programmatic filter buttons |
 | `/examples/grouping` | Hierarchical grouping with aggregations |
 | `/examples/custom-cells` | Currency, date, boolean, rating star formatters |
-| `/examples/raw-query` | JOIN, aggregate, CTE queries via the `query` prop |
+| `/examples/raw-query` | JOIN, aggregate, CTE queries via `query` prop with full toolbar |
 
 Run `npm run dev` and visit `http://localhost:5173/examples/minimal` to start.
 

package/dist/GridLite.svelte

@@ -164,33 +164,31 @@ async function rebuildQuery() {
   }
   let sql;
   let params = [];
-  if (query) {
-    sql = query;
-  } else if (table) {
-    if (isGrouped) {
-      await rebuildGroupedQuery();
-      return;
-    }
-    const usePagination = features.pagination !== false;
-    const built = buildQuery({
-      table,
-      filters,
-      filterLogic,
-      sorting,
-      page: usePagination ? page : void 0,
-      pageSize: usePagination ? pageSize : void 0,
-      allowedColumns,
-      globalSearch: globalFilter || void 0
-    });
-    sql = built.sql;
-    params = built.params;
-    if (usePagination) {
-      await updateTotalCount();
-    }
-  } else {
+  const querySource = query ? { source: query } : table ? { table } : null;
+  if (!querySource) {
     error = "Either `table` or `query` prop is required";
     return;
   }
+  if (isGrouped) {
+    await rebuildGroupedQuery();
+    return;
+  }
+  const usePagination = features.pagination !== false;
+  const built = buildQuery({
+    ...querySource,
+    filters,
+    filterLogic,
+    sorting,
+    page: usePagination ? page : void 0,
+    pageSize: usePagination ? pageSize : void 0,
+    allowedColumns,
+    globalSearch: globalFilter || void 0
+  });
+  sql = built.sql;
+  params = built.params;
+  if (usePagination) {
+    await updateTotalCount();
+  }
   groupData = [];
   expandedGroups = /* @__PURE__ */ new Set();
   totalGroups = 0;
@@ -216,12 +214,13 @@ function cleanAgg(g) {
   };
 }
 async function rebuildGroupedQuery() {
-  if (!table) return;
+  const querySource = query ? { source: query } : table ? { table } : null;
+  if (!querySource) return;
   try {
     const usePagination = features.pagination !== false;
     const topGroupConfig = cleanAgg(validGrouping[0]);
     const summaryQuery = buildGroupSummaryQuery({
-      table,
+      ...querySource,
       grouping: [topGroupConfig],
       filters,
       filterLogic,
@@ -237,7 +236,7 @@ async function rebuildGroupedQuery() {
     );
     if (usePagination) {
       const countQuery = buildGroupCountQuery({
-        table,
+        ...querySource,
         grouping: [topGroupConfig],
         filters,
         filterLogic,
@@ -283,7 +282,8 @@ async function rebuildGroupedQuery() {
   }
 }
 async function fetchGroupChildren(group) {
-  if (!table) return;
+  const querySource = query ? { source: query } : table ? { table } : null;
+  if (!querySource) return;
   const key = groupKey(group);
   groupLoading = /* @__PURE__ */ new Set([...groupLoading, key]);
   try {
@@ -295,7 +295,7 @@ async function fetchGroupChildren(group) {
     if (nextDepth < validGrouping.length) {
       const subGroupConfig = cleanAgg(validGrouping[nextDepth]);
       const summaryQuery = buildGroupSummaryQuery({
-        table,
+        ...querySource,
         grouping: [subGroupConfig],
         filters: [
           ...filters,
@@ -334,7 +334,7 @@ async function fetchGroupChildren(group) {
       updateGroupInTree(key, { subGroups });
     } else {
       const detailQuery = buildGroupDetailQuery({
-        table,
+        ...querySource,
         groupValues: parentValues,
         filters,
         filterLogic,
@@ -372,10 +372,11 @@ function updateGroupNode(node, targetKey, updates) {
   return node;
 }
 async function updateTotalCount() {
-  if (!table) return;
+  const querySource = query ? { source: query } : table ? { table } : null;
+  if (!querySource) return;
   try {
     const countQuery = buildCountQuery({
-      table,
+      ...querySource,
       filters,
       filterLogic,
       allowedColumns,
@@ -804,7 +805,7 @@ onDestroy(() => {
 	{:else if storeState.error}
 		<div class="gridlite-empty">Error: {storeState.error.message}</div>
 	{:else}
-		{#if table && toolbarLayout !== 'aggrid'}
+		{#if toolbarLayout !== 'aggrid'}
 			<div class="gridlite-toolbar">
 				<!-- Custom toolbar content (start) -->
 				<slot name="toolbar-start" />
@@ -847,7 +848,8 @@ onDestroy(() => {
 					<div class="gridlite-toolbar-filter">
 						<FilterBar
 							{db}
-							{table}
+							table={table ?? ''}
+							source={query ?? ''}
 							{columns}
 							columnConfigs={mergedColumnConfigs}
 							{allowedColumns}
@@ -993,7 +995,7 @@ onDestroy(() => {
 			</div>
 		{/if}
 
-		{#if table && toolbarLayout === 'aggrid'}
+		{#if toolbarLayout === 'aggrid'}
 			<!-- AG Grid layout: sidebar on right, minimal toolbar on top -->
 			<!-- TODO(#1): aggrid layout is experimental — not production-ready. Needs debugging. -->
 			<div class="gridlite-toolbar gridlite-toolbar-aggrid-top">
@@ -1159,32 +1161,30 @@ onDestroy(() => {
 										{getColumnLabel(col)}
 									</span>
 								{/if}
-								{#if table}
-									<button
-										class="gridlite-th-menu-btn"
-										on:click|stopPropagation={() =>
-											(columnMenuOpen = columnMenuOpen === col.name ? null : col.name)}
-										title="Column options"
-										type="button"
-									>
-										<svg width="14" height="14" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-											<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
-										</svg>
-									</button>
-									<ColumnMenu
-										columnName={col.name}
-										isOpen={columnMenuOpen === col.name}
-										{sorting}
-										canSort={features.sorting ?? false}
-										canFilter={features.filtering ?? false}
-										canGroup={features.grouping ?? false}
-										onSort={handleColumnMenuSort}
-										onFilter={handleColumnMenuFilter}
-										onGroup={handleColumnMenuGroup}
-										onHide={handleColumnMenuHide}
-										onClose={() => (columnMenuOpen = null)}
-									/>
-								{/if}
+								<button
+									class="gridlite-th-menu-btn"
+									on:click|stopPropagation={() =>
+										(columnMenuOpen = columnMenuOpen === col.name ? null : col.name)}
+									title="Column options"
+									type="button"
+								>
+									<svg width="14" height="14" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+										<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
+									</svg>
+								</button>
+								<ColumnMenu
+									columnName={col.name}
+									isOpen={columnMenuOpen === col.name}
+									{sorting}
+									canSort={features.sorting ?? false}
+									canFilter={features.filtering ?? false}
+									canGroup={features.grouping ?? false}
+									onSort={handleColumnMenuSort}
+									onFilter={handleColumnMenuFilter}
+									onGroup={handleColumnMenuGroup}
+									onHide={handleColumnMenuHide}
+									onClose={() => (columnMenuOpen = null)}
+								/>
 							</div>
 							{#if features.columnResizing}
 								<!-- svelte-ignore a11y-no-static-element-interactions -->
@@ -1401,6 +1401,7 @@ onDestroy(() => {
 						<FilterBar
 							{db}
 							table={table ?? ''}
+							source={query ?? ''}
 							{columns}
 							columnConfigs={mergedColumnConfigs}
 							{allowedColumns}

package/dist/components/FilterBar.svelte

@@ -1,7 +1,8 @@
-<script>import { quoteIdentifier } from "../query/builder.js";
+<script>import { quoteIdentifier, resolveFrom } from "../query/builder.js";
 import FilterConditionComponent from "./FilterCondition.svelte";
 export let db;
-export let table;
+export let table = "";
+export let source = "";
 export let columns;
 export let columnConfigs = [];
 export let allowedColumns = [];
@@ -14,13 +15,14 @@ export let onExpandedChange = void 0;
 let columnValuesCache = /* @__PURE__ */ new Map();
 let numericRangeCache = /* @__PURE__ */ new Map();
 async function getColumnValues(columnName) {
-  if (!columnName || !table) return [];
+  if (!columnName || !table && !source) return [];
   if (columnValuesCache.has(columnName)) {
     return columnValuesCache.get(columnName);
   }
   try {
+    const fromClause = resolveFrom(table || void 0, source || void 0);
     const quotedCol = quoteIdentifier(columnName, allowedColumns);
-    const sql = `SELECT DISTINCT ${quotedCol}::TEXT AS val FROM ${quoteIdentifier(table)} WHERE ${quotedCol} IS NOT NULL ORDER BY val LIMIT 200`;
+    const sql = `SELECT DISTINCT ${quotedCol}::TEXT AS val FROM ${fromClause} WHERE ${quotedCol} IS NOT NULL ORDER BY val LIMIT 200`;
     const result = await db.query(sql);
     const values = result.rows.map((r) => r.val);
     columnValuesCache.set(columnName, values);
@@ -31,7 +33,7 @@ async function getColumnValues(columnName) {
   }
 }
 async function getNumericRange(columnName) {
-  if (!columnName || !table) return null;
+  if (!columnName || !table && !source) return null;
   if (numericRangeCache.has(columnName)) {
     return numericRangeCache.get(columnName);
   }
@@ -43,8 +45,9 @@ async function getNumericRange(columnName) {
     return null;
   }
   try {
+    const fromClause = resolveFrom(table || void 0, source || void 0);
     const quotedCol = quoteIdentifier(columnName, allowedColumns);
-    const sql = `SELECT MIN(${quotedCol})::NUMERIC AS min_val, MAX(${quotedCol})::NUMERIC AS max_val FROM ${quoteIdentifier(table)}`;
+    const sql = `SELECT MIN(${quotedCol})::NUMERIC AS min_val, MAX(${quotedCol})::NUMERIC AS max_val FROM ${fromClause}`;
     const result = await db.query(sql);
     const row = result.rows[0];
     if (row && row.min_val != null && row.max_val != null) {

package/dist/components/FilterBar.svelte.d.ts

@@ -10,7 +10,8 @@ import type { PGliteWithLive } from '../query/live.js';
 declare const __propDef: {
     props: {
         /** PGLite instance for running suggestion queries */ db: PGliteWithLive;
-        /** Table name for suggestion queries */ table: string;
+        /** Table name for suggestion queries (mutually exclusive with `source`) */ table?: string;
+        /** Raw SQL subquery source for suggestion queries (mutually exclusive with `table`) */ source?: string;
         /** Introspected column metadata */ columns: ColumnMetadata[];
         /** Column config overrides (labels, dataType, selectOptions) */ columnConfigs?: ColumnConfig[];
         /** Allowed column names for query safety */ allowedColumns?: string[];

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { default as ColumnMenu } from "./components/ColumnMenu.svelte";
 export { default as ColumnPicker } from "./components/ColumnPicker.svelte";
 export { default as RowDetailModal } from "./components/RowDetailModal.svelte";
 export type { GridLiteProps, GridConfig, GridFeatures, GridState, ColumnConfig, ColumnDataType, ColumnMetadata, FilterCondition, FilterOperator, FilterLogic, SortConfig, GroupConfig, AggregationConfig, AggregateFunction, ViewPreset, ClassNameMap, RowHeight, ColumnSpacing, ParameterizedQuery, ToolbarLayout, } from "./types.js";
-export { quoteIdentifier, buildWhereClause, buildOrderByClause, buildGroupByClause, buildPaginationClause, buildGlobalSearchClause, buildGroupSummaryQuery, buildGroupCountQuery, buildGroupDetailQuery, buildQuery, buildCountQuery, } from "./query/builder.js";
+export { quoteIdentifier, resolveFrom, buildWhereClause, buildOrderByClause, buildGroupByClause, buildPaginationClause, buildGlobalSearchClause, buildGroupSummaryQuery, buildGroupCountQuery, buildGroupDetailQuery, buildQuery, buildCountQuery, } from "./query/builder.js";
 export type { QueryOptions, GroupSummaryOptions, GroupDetailOptions, } from "./query/builder.js";
 export { mapPostgresType, mapOidToDataType, introspectTable, getColumnNames, } from "./query/schema.js";
 export { createLiveQueryStore, createLiveQueryStoreFromQuery, } from "./query/live.js";

package/dist/index.js

@@ -12,7 +12,7 @@ export { default as ColumnMenu } from "./components/ColumnMenu.svelte";
 export { default as ColumnPicker } from "./components/ColumnPicker.svelte";
 export { default as RowDetailModal } from "./components/RowDetailModal.svelte";
 // Query builder
-export { quoteIdentifier, buildWhereClause, buildOrderByClause, buildGroupByClause, buildPaginationClause, buildGlobalSearchClause, buildGroupSummaryQuery, buildGroupCountQuery, buildGroupDetailQuery, buildQuery, buildCountQuery, } from "./query/builder.js";
+export { quoteIdentifier, resolveFrom, buildWhereClause, buildOrderByClause, buildGroupByClause, buildPaginationClause, buildGlobalSearchClause, buildGroupSummaryQuery, buildGroupCountQuery, buildGroupDetailQuery, buildQuery, buildCountQuery, } from "./query/builder.js";
 // Schema introspection
 export { mapPostgresType, mapOidToDataType, introspectTable, getColumnNames, } from "./query/schema.js";
 // Live query store

package/dist/query/builder.d.ts

@@ -9,6 +9,12 @@
  * to prevent SQL injection via identifier manipulation.
  */
 import type { FilterCondition, FilterLogic, SortConfig, GroupConfig, ParameterizedQuery } from "../types.js";
+/**
+ * Resolve a FROM clause from either a table name or a raw SQL source.
+ * When `source` is provided, it's used as a subquery: `(source) AS _gridlite_sub`.
+ * When `table` is provided, it's quoted as an identifier: `"table"`.
+ */
+export declare function resolveFrom(table?: string, source?: string): string;
 /**
  * Validate and quote a column name as a SQL identifier.
  * Throws if the name is not a valid identifier.
@@ -59,8 +65,10 @@ export declare function buildPaginationClause(page: number, pageSize: number): s
  */
 export declare function buildGlobalSearchClause(searchTerm: string, textColumns: string[], paramOffset?: number, allowedColumns?: string[]): ParameterizedQuery;
 export interface GroupSummaryOptions {
-    /** Table name */
-    table: string;
+    /** Table name (mutually exclusive with `source`) */
+    table?: string;
+    /** Raw SQL subquery source (mutually exclusive with `table`) */
+    source?: string;
     /** Group columns (max 3) */
     grouping: GroupConfig[];
     /** Filter conditions to apply before grouping */
@@ -94,8 +102,10 @@ export declare function buildGroupSummaryQuery(options: GroupSummaryOptions): Pa
  */
 export declare function buildGroupCountQuery(options: GroupSummaryOptions): ParameterizedQuery;
 export interface GroupDetailOptions {
-    /** Table name */
-    table: string;
+    /** Table name (mutually exclusive with `source`) */
+    table?: string;
+    /** Raw SQL subquery source (mutually exclusive with `table`) */
+    source?: string;
     /** Values to match for parent groups: [{ column: "department", value: "Engineering" }] */
     groupValues: {
         column: string;
@@ -125,8 +135,10 @@ export interface GroupDetailOptions {
  */
 export declare function buildGroupDetailQuery(options: GroupDetailOptions): ParameterizedQuery;
 export interface QueryOptions {
-    /** Table name to query */
-    table: string;
+    /** Table name to query (mutually exclusive with `source`) */
+    table?: string;
+    /** Raw SQL subquery source (mutually exclusive with `table`) */
+    source?: string;
     /** Filter conditions */
     filters?: FilterCondition[];
     /** Filter logic (and/or) */

package/dist/query/builder.js

@@ -8,6 +8,21 @@
  * Column names are validated against an allowlist (from schema introspection)
  * to prevent SQL injection via identifier manipulation.
  */
+// ─── Source Resolution ──────────────────────────────────────────────────────
+/**
+ * Resolve a FROM clause from either a table name or a raw SQL source.
+ * When `source` is provided, it's used as a subquery: `(source) AS _gridlite_sub`.
+ * When `table` is provided, it's quoted as an identifier: `"table"`.
+ */
+export function resolveFrom(table, source) {
+    if (source) {
+        return `(${source}) AS _gridlite_sub`;
+    }
+    if (table) {
+        return quoteIdentifier(table);
+    }
+    throw new Error("Either `table` or `source` must be provided");
+}
 // ─── Column Name Validation ─────────────────────────────────────────────────
 /**
  * Valid SQL identifier pattern: letters, digits, underscores.
@@ -222,11 +237,11 @@ export function buildGlobalSearchClause(searchTerm, textColumns, paramOffset = 0
  *   FROM "employees" WHERE ... GROUP BY "department" ORDER BY "department"
  */
 export function buildGroupSummaryQuery(options) {
-    const { table, grouping, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, sorting = [], page, pageSize, } = options;
+    const { table, source, grouping, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, sorting = [], page, pageSize, } = options;
     if (grouping.length === 0) {
         throw new Error("buildGroupSummaryQuery requires at least one group");
     }
-    const tableName = quoteIdentifier(table);
+    const fromClause = resolveFrom(table, source);
     const { selectColumns, groupBy } = buildGroupByClause(grouping, allowedColumns);
     // WHERE from filters
     const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
@@ -260,7 +275,7 @@ export function buildGroupSummaryQuery(options) {
         : "";
     const parts = [
         `SELECT ${selectColumns}`,
-        `FROM ${tableName}`,
+        `FROM ${fromClause}`,
         whereSQL,
         groupBy,
         orderBy,
@@ -272,11 +287,11 @@ export function buildGroupSummaryQuery(options) {
  * Build a count query for group summaries (how many groups exist).
  */
 export function buildGroupCountQuery(options) {
-    const { table, grouping, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, } = options;
+    const { table, source, grouping, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, } = options;
     if (grouping.length === 0) {
         throw new Error("buildGroupCountQuery requires at least one group");
     }
-    const tableName = quoteIdentifier(table);
+    const fromClause = resolveFrom(table, source);
     const groupCols = grouping.map((g) => quoteIdentifier(g.column, allowedColumns));
     const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
     const searchCols = searchColumns ?? allowedColumns ?? [];
@@ -293,7 +308,7 @@ export function buildGroupCountQuery(options) {
         whereSQL = `WHERE ${globalSearchClause.sql}`;
     }
     const parts = [
-        `SELECT COUNT(*) AS "total" FROM (SELECT 1 FROM ${tableName}`,
+        `SELECT COUNT(*) AS "total" FROM (SELECT 1 FROM ${fromClause}`,
         whereSQL,
         `GROUP BY ${groupCols.join(", ")}`,
         `) AS "_groups"`,
@@ -310,11 +325,11 @@ export function buildGroupCountQuery(options) {
  *   SELECT * FROM "employees" WHERE ... AND "department" = $N ORDER BY ...
  */
 export function buildGroupDetailQuery(options) {
-    const { table, groupValues, filters = [], filterLogic = "and", sorting = [], allowedColumns, globalSearch, searchColumns, } = options;
+    const { table, source, groupValues, filters = [], filterLogic = "and", sorting = [], allowedColumns, globalSearch, searchColumns, } = options;
     if (groupValues.length === 0) {
         throw new Error("buildGroupDetailQuery requires at least one group value");
     }
-    const tableName = quoteIdentifier(table);
+    const fromClause = resolveFrom(table, source);
     // Base WHERE from filters
     const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
     // Global search
@@ -345,7 +360,7 @@ export function buildGroupDetailQuery(options) {
     const allWhereParts = [...baseWhereParts, ...groupConstraints];
     const whereSQL = allWhereParts.length > 0 ? `WHERE ${allWhereParts.join(" AND ")}` : "";
     const orderBy = buildOrderByClause(sorting, allowedColumns);
-    const parts = [`SELECT *`, `FROM ${tableName}`, whereSQL, orderBy].filter(Boolean);
+    const parts = [`SELECT *`, `FROM ${fromClause}`, whereSQL, orderBy].filter(Boolean);
     return { sql: parts.join(" "), params: allParams };
 }
 /**
@@ -355,8 +370,8 @@ export function buildGroupDetailQuery(options) {
  * WHERE, ORDER BY, GROUP BY, and LIMIT/OFFSET clauses into a single query.
  */
 export function buildQuery(options) {
-    const { table, filters = [], filterLogic = "and", sorting = [], grouping = [], page, pageSize, allowedColumns, globalSearch, searchColumns, } = options;
-    const tableName = quoteIdentifier(table);
+    const { table, source, filters = [], filterLogic = "and", sorting = [], grouping = [], page, pageSize, allowedColumns, globalSearch, searchColumns, } = options;
+    const fromClause = resolveFrom(table, source);
     // GROUP BY affects SELECT columns
     const { selectColumns, groupBy } = buildGroupByClause(grouping, allowedColumns);
     // WHERE clause from filters
@@ -386,7 +401,7 @@ export function buildQuery(options) {
     // Compose
     const parts = [
         `SELECT ${selectColumns}`,
-        `FROM ${tableName}`,
+        `FROM ${fromClause}`,
         whereSQL,
         groupBy,
         orderBy,
@@ -402,8 +417,8 @@ export function buildQuery(options) {
  * Uses the same filters but no sorting/grouping/pagination.
  */
 export function buildCountQuery(options) {
-    const { table, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, } = options;
-    const tableName = quoteIdentifier(table);
+    const { table, source, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, } = options;
+    const fromClause = resolveFrom(table, source);
     const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
     // Global search clause
     const searchCols = searchColumns ?? allowedColumns ?? [];
@@ -422,7 +437,7 @@ export function buildCountQuery(options) {
     }
     const parts = [
         'SELECT COUNT(*) AS "total"',
-        `FROM ${tableName}`,
+        `FROM ${fromClause}`,
         whereSQL,
     ].filter(Boolean);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotleybuilder/svelte-gridlite-kit",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A SQL-native data grid component for Svelte and SvelteKit, powered by PGLite",
   "author": "Sertantai",
   "license": "MIT",