@pythia-software/query-table-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 query-table contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @pythia-software/query-table-ui
+
+Opinionated, themeable React components for query-table, including the data
+table, query builder, field picker, metrics panel, saved queries, cell menus,
+and selection toolbar.
+
+## Install
+
+```bash
+npm install @pythia-software/query-table-core @pythia-software/query-table-react @pythia-software/query-table-ui react
+```
+
+## Use
+
+```tsx
+import { DataTable, QueryBuilder, defaultRenderers } from "@pythia-software/query-table-ui";
+import "@pythia-software/query-table-ui/theme.css";
+
+export function OrdersTable({ table, schema }) {
+  return (
+    <>
+      <QueryBuilder
+        api={table}
+        fields={schema.fields}
+        total={table.total}
+        running={table.loading}
+      />
+      <DataTable
+        fields={table.visibleFields}
+        rows={table.rows}
+        query={table.query}
+        onQueryChange={table.setQuery}
+        renderers={defaultRenderers}
+        rowId={table.rowId}
+        total={table.total}
+        loading={table.loading}
+      />
+    </>
+  );
+}
+```
+
+The bundled `link` renderer allows only HTTP(S), email, telephone, relative,
+and fragment URLs. Applications remain responsible for validating URLs emitted
+by custom renderers.
+
+See the [repository README](https://github.com/Pythia-Software/query-table#readme)
+for customization and backend integration details.

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+import { ReactNode, SetStateAction } from 'react';
+import { FieldDef, QueryState, RowId, FieldStats, WhereClause } from '@pythia-software/query-table-core';
+import { SelectionApi, ColumnDragApi, QueryTableApi, AggregationsApi, SavedQueriesApi } from '@pythia-software/query-table-react';
+
+interface CellContext<Row = any, V = unknown> {
+    value: V;
+    row: Row;
+    field: FieldDef<Row, V>;
+    /** Current query — lets renderers reflect active state (e.g. highlight matches). */
+    query: QueryState;
+}
+type CellRenderer<Row = any, V = unknown> = (ctx: CellContext<Row, V>) => ReactNode;
+type RenderRegistry<Row = any> = Record<string, CellRenderer<Row>>;
+/** Resolve a user-controlled link against a harmless HTTPS base and allow only
+ * navigation protocols. This catches obfuscated forms such as `java\nscript:`
+ * that simple prefix checks miss while preserving relative and fragment URLs. */
+declare function safeLinkHref(value: unknown): string | null;
+/** Generic, domain-free renderers shipped with the package. Keys are stable and
+ *  referenced from FieldDef.render. Consumers spread these and add their own. */
+declare const defaultRenderers: RenderRegistry;
+/** Resolve a FieldDef's renderer: inline fn wins, else registry lookup, else
+ *  the `text` fallback. */
+declare function resolveRenderer<Row>(field: FieldDef<Row>, registry: RenderRegistry<Row>): CellRenderer<Row>;
+
+interface TableClassNames {
+    wrap?: string;
+    table?: string;
+    thead?: string;
+    headerRow?: string;
+    th?: string;
+    resizeHandle?: string;
+    tbody?: string;
+    row?: string;
+    rowSelected?: string;
+    cell?: string;
+    checkboxCell?: string;
+    loadingBar?: string;
+    empty?: string;
+    summaryRow?: string;
+    summaryCell?: string;
+    summaryControls?: string;
+    summaryHint?: string;
+    summaryButton?: string;
+}
+interface QueryBuilderClassNames {
+    root?: string;
+    chip?: string;
+    columnChip?: string;
+    button?: string;
+    input?: string;
+    select?: string;
+}
+interface MenuClassNames {
+    popover?: string;
+    item?: string;
+    separator?: string;
+}
+
+interface DataTableProps<Row> {
+    /** Ordered visible fields (widths already resolved), from `api.visibleFields`. */
+    fields: FieldDef<Row>[];
+    rows: Row[];
+    query: QueryState;
+    onQueryChange: (q: SetStateAction<QueryState>) => void;
+    /** Resolves FieldDef.render keys. Pass `{ ...defaultRenderers, ...yours }`. */
+    renderers: RenderRegistry<Row>;
+    /** Row → stable id (defaults to reading the schema's idField). */
+    rowId: (row: Row) => RowId | null;
+    /** Optional checkbox column + selection behavior (from `api.selection`). */
+    selection?: SelectionApi;
+    /** Shared column-reorder drag state (`api.columnDrag`). Pass it so dragging a
+     *  table header also live-previews/dims the matching QueryBuilder select chip
+     *  (and vice versa). Omit for a self-contained, table-only drag. */
+    columnDrag?: ColumnDragApi;
+    /** Always-visible trailing column (row actions, links). */
+    trailing?: (row: Row) => ReactNode;
+    trailingLabel?: string;
+    /** Total matching rows before pagination, when known. */
+    total?: number | null;
+    loading?: boolean;
+    emptyMessage?: string;
+    /** Tailwind / bespoke styling slots (Mode B). */
+    classNames?: TableClassNames;
+}
+declare function DataTable<Row>(props: DataTableProps<Row>): ReactNode;
+
+interface QueryBuilderProps<Row> {
+    /** The controller; QueryBuilder drives it through the intent helpers. */
+    api: QueryTableApi<Row>;
+    /** All schema fields (for the field picker / sort picker). */
+    fields: FieldDef<Row>[];
+    /** Total matching rows, for the "N of M" paging hint. */
+    total: number | null;
+    /** Disable inputs while a fetch is in flight. */
+    running?: boolean;
+    classNames?: QueryBuilderClassNames;
+    /** Use this to control collapse state from a parent UI. */
+    collapsed?: boolean;
+    /** Controlled collapse callback (use when `collapsed` is provided). */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Initial collapse state for uncontrolled mode. */
+    defaultCollapsed?: boolean;
+}
+declare function QueryBuilder<Row>({ api, fields, total, running, classNames, collapsed, onCollapsedChange, defaultCollapsed, }: QueryBuilderProps<Row>): ReactNode;
+
+interface MetricsPanelProps<Row> {
+    /** The aggregation API from useQueryTable (clauses + results + status). */
+    aggregations: AggregationsApi;
+    /** All schema fields, to resolve labels + the measure field's renderer. */
+    fields: FieldDef<Row>[];
+    /** Cell renderers (same registry as the table) for formatting measure values. */
+    renderers?: RenderRegistry<Row>;
+    /** Hidden entirely when there are no metrics unless this is set. */
+    emptyMessage?: string;
+    classNames?: {
+        root?: string;
+        metric?: string;
+    };
+}
+declare function MetricsPanel<Row>({ aggregations, fields, renderers, emptyMessage, classNames, }: MetricsPanelProps<Row>): ReactNode;
+
+interface FieldPickerProps<Row> {
+    fields: FieldDef<Row>[];
+    /** Already-shown field names, so the picker can mark/hide them. */
+    excluded?: string[];
+    /** Stats keyed by field name (optional). */
+    stats?: Record<string, FieldStats>;
+    /** When true, dim/disable fields with ≤1 distinct value ("gate on distinct"). */
+    gateOnDistinct?: boolean;
+    onPick: (field: FieldDef<Row>) => void;
+    onClose?: () => void;
+}
+declare function FieldPicker<Row>({ fields, excluded, stats, gateOnDistinct, onPick, onClose, }: FieldPickerProps<Row>): ReactNode;
+
+interface CellMenuProps<Row> {
+    field: FieldDef<Row>;
+    value: unknown;
+    /** Viewport coordinates of the click. */
+    x: number;
+    y: number;
+    onAddFilter: (clause: WhereClause) => void;
+    onClose: () => void;
+    classNames?: MenuClassNames;
+}
+declare function CellMenu<Row>({ field, value, x, y, onAddFilter, onClose, classNames }: CellMenuProps<Row>): ReactNode;
+
+interface SelectionToolbarProps {
+    selection: SelectionApi;
+    /** Consumer-rendered action buttons. Receives the selected ids so the consumer
+     *  can gate/enable actions (e.g. mixed-state rules). */
+    actions: (selectedIds: RowId[]) => ReactNode;
+    /** Hidden when nothing is selected unless `alwaysShow`. */
+    alwaysShow?: boolean;
+    className?: string;
+}
+declare function SelectionToolbar({ selection, actions, alwaysShow, className }: SelectionToolbarProps): ReactNode;
+
+interface SavedQueriesModalProps {
+    saved: SavedQueriesApi;
+    onClose: () => void;
+    onLoad?: (savedId: string) => void;
+}
+declare function SavedQueriesModal({ saved, onClose, onLoad }: SavedQueriesModalProps): ReactNode;
+
+export { type CellContext, CellMenu, type CellMenuProps, type CellRenderer, DataTable, type DataTableProps, FieldPicker, type FieldPickerProps, type MenuClassNames, MetricsPanel, type MetricsPanelProps, QueryBuilder, type QueryBuilderClassNames, type QueryBuilderProps, type RenderRegistry, SavedQueriesModal, type SavedQueriesModalProps, SelectionToolbar, type SelectionToolbarProps, type TableClassNames, defaultRenderers, resolveRenderer, safeLinkHref };