@quillsql/react 2.16.46 → 2.16.48

package/dist/index.cjs

@@ -15116,11 +15116,11 @@ function isValidPivot(pivot) {
       reason: 'Value field cannot be empty when aggregation is not "count" or "percentage"'
     };
   } else if (pivot.aggregations?.some(
-    (a) => a.aggregationType === "percentage" && !a.valueField && (!pivot.rowField || pivot.columnField)
+    (a) => a.aggregationType === "percentage" && !a.valueField && !pivot.rowField
   )) {
     return {
       valid: false,
-      reason: "Empty percentage field only supported for pivot tables with a row field and no column field"
+      reason: "Empty percentage field only supported for pivot tables with a row field"
     };
   }
   return { valid: true, reason: "" };
@@ -16403,7 +16403,7 @@ function formatAggregationTypeForDisplay(aggregationType) {
     case "max":
       return "Max";
     case "percentage":
-      return "Percentage";
+      return "Percent";
     default:
       return aggregationType ? capitalize(String(aggregationType)) : "Value";
   }
@@ -16445,6 +16445,21 @@ function getDefaultPivotMeasureLabel(report) {
     return pivot.columnField ? "Count" : `Count ${snakeAndCamelCaseToTitleCase(tableNames[0] ?? "table")}`;
   }
   const target = valueField !== void 0 && String(valueField).trim() ? resolveValueFieldDisplayLabel(report, valueField) : tableNames.length > 0 ? tableNames.map((n) => snakeAndCamelCaseToTitleCase(n)).join(", ") : "table";
+  if (aggregationType.toLowerCase() === "percentage") {
+    const valueField2 = String(
+      fromAggregations?.valueField2 ?? ""
+    ).trim();
+    if (valueField && valueField2) {
+      return `Percent ${target} of ${resolveValueFieldDisplayLabel(report, valueField2)}`;
+    }
+    const valueFieldType = String(
+      fromAggregations?.valueFieldType ?? ""
+    ).trim().toLowerCase();
+    if (valueField && valueFieldType === "bool") {
+      return `Percent ${target}`;
+    }
+    return `Percent of Total ${target}`;
+  }
   return target ? `${aggWord} ${target}` : aggWord;
 }
 function humanizeLegacyPivotMeasureLabelFragment(text) {
@@ -16452,7 +16467,10 @@ function humanizeLegacyPivotMeasureLabelFragment(text) {
   if (!t) return t;
   const m = t.match(LEGACY_AGG_SNAKE_FIELD);
   if (!m) return t;
-  return `${formatAggregationTypeForDisplay(m[1])} ${snakeAndCamelCaseToTitleCase(m[2])}`;
+  if (String(m[1]).toLowerCase() === "percentage") {
+    return `Percent of Total ${snakeAndCamelCaseToTitleCase(m[2] ?? "")}`;
+  }
+  return `${formatAggregationTypeForDisplay(m[1])} ${snakeAndCamelCaseToTitleCase(m[2] ?? "")}`;
 }
 function humanizeChartSeriesTooltipLabel(label) {
   const s = String(label ?? "").trim();
@@ -59847,7 +59865,8 @@ var AGGREGATION_OPTION_TYPES = [
   "average",
   "count",
   "max",
-  "min"
+  "min",
+  "percentage"
 ];
 var QUERY_BUILDER_MULTI_VALUE_OPERATORS = /* @__PURE__ */ new Set(["in", "notin"]);
 var TABLE_FORMAT_CACHE_MAX_ENTRIES = 5e3;
@@ -60337,9 +60356,31 @@ function buildPivotAggregationsWithFieldTables({
       schemaTables,
       preferredTables
     }) || void 0;
+    const isPercentageAggregation = String(aggregation.aggregationType ?? "").toLowerCase() === "percentage";
+    const typeFallbackColumns = [
+      ...sourceReport?.columnInternal ?? sourceReport?.columns ?? []
+    ];
+    const valueFieldType = String(
+      aggregation.valueFieldType ?? ""
+    ).trim() || (isPercentageAggregation ? resolveFieldType({
+      field: aggregation.valueField,
+      table: valueFieldTable,
+      schemaTables,
+      fallbackColumns: typeFallbackColumns
+    }) : void 0);
+    const valueField2Type = String(
+      aggregation.valueField2Type ?? ""
+    ).trim() || (isPercentageAggregation ? resolveFieldType({
+      field: aggregation.valueField2,
+      table: valueFieldTable,
+      schemaTables,
+      fallbackColumns: typeFallbackColumns
+    }) : void 0);
     result.push({
       ...aggregationWithoutPivotTables,
       aggregationType: aggregation.aggregationType,
+      ...valueFieldType ? { valueFieldType } : {},
+      ...valueField2Type ? { valueField2Type } : {},
       ...valueFieldTable ? { valueFieldTable } : {}
     });
   }
@@ -60383,8 +60424,9 @@ function getPivotAggregationSortFields(aggregationState, resolvedColumnField) {
     const aggregationType = String(aggregation.aggregationType ?? "").trim();
     if (!aggregationType) continue;
     const valueField = String(aggregation.valueField ?? "").trim();
-    const canonicalBaseField = valueField || "count";
-    const sortField = hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
+    const isValuelessPercentage = !valueField && aggregationType.toLowerCase() === "percentage";
+    const canonicalBaseField = valueField || (isValuelessPercentage ? "percentage" : "count");
+    const sortField = isValuelessPercentage ? "percentage" : hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
     if (!seen.has(sortField)) {
       seen.add(sortField);
       fields.push(sortField);
@@ -60403,8 +60445,9 @@ function getPivotAggregationSortLabelOverrides(aggregationState, aggregationTabl
     const aggregationType = String(aggregation.aggregationType ?? "").trim();
     if (!aggregationType) continue;
     const valueField = String(aggregation.valueField ?? "").trim();
-    const canonicalBaseField = valueField || "count";
-    const sortField = hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
+    const isValuelessPercentage = !valueField && aggregationType.toLowerCase() === "percentage";
+    const canonicalBaseField = valueField || (isValuelessPercentage ? "percentage" : "count");
+    const sortField = isValuelessPercentage ? "percentage" : hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
     if (labelBySortField.has(sortField)) continue;
     if (valueField || aggregationType.toLowerCase() !== "count") continue;
     const tableHint = String(aggregationTablesByIndex[index] ?? "").trim();
@@ -60558,6 +60601,9 @@ function trimAggregationSuffix(value, aggregationType) {
 }
 function getAggregationFieldKey(aggregation, hasMultipleAggregations) {
   if (!aggregation.aggregationType) return null;
+  if (!aggregation.valueField && aggregation.aggregationType === "percentage") {
+    return "percentage";
+  }
   if (aggregation.valueField) {
     return hasMultipleAggregations ? `${aggregation.valueField}_${aggregation.aggregationType}` : aggregation.valueField;
   }
@@ -60678,6 +60724,22 @@ function buildAggregationLabel(aggregation, report) {
   }
   const rawTarget = aggregation.valueField ?? (tableNames.length > 0 ? tableNames.join(", ") : "table");
   const target = report ? aggregation.valueField ? resolveValueFieldDisplayLabel(report, aggregation.valueField) : rawTarget : rawTarget;
+  if (String(aggregationType).toLowerCase() === "percentage") {
+    const valueField2 = String(
+      aggregation.valueField2 ?? ""
+    ).trim();
+    if (aggregation.valueField && valueField2) {
+      const denominator = report ? resolveValueFieldDisplayLabel(report, valueField2) : valueField2;
+      return `Percent ${target} of ${denominator}`;
+    }
+    const valueFieldType = String(
+      aggregation.valueFieldType ?? ""
+    ).trim().toLowerCase();
+    if (aggregation.valueField && valueFieldType === "bool") {
+      return `Percent ${target}`;
+    }
+    return `Percent of Total ${target}`;
+  }
   return target ? `${aggWord} ${target}` : aggWord;
 }
 function normalizePivotColumnDisplayValue(value) {
@@ -60817,6 +60879,13 @@ function normalizePivotChartForDisplay(chart) {
     if (aggregation?.aggregationType === "count") {
       return "whole_number";
     }
+    if (aggregation?.aggregationType === "percentage") {
+      const savedFormat = yAxisFormatByField.get(field);
+      if (savedFormat === "percent" || savedFormat === "percentage") {
+        return savedFormat;
+      }
+      return "percentage";
+    }
     const directAxisFormat = yAxisFormatByField.get(field);
     if (directAxisFormat) return directAxisFormat;
     const aggType = aggregation?.aggregationType ? String(aggregation.aggregationType) : void 0;
@@ -62013,7 +62082,8 @@ function processPivotState(next, options = {}) {
   const {
     nextState,
     promoteColumnToRow = false,
-    fallbackColumnGroupBy
+    fallbackColumnGroupBy,
+    isBoolAggregationField
   } = options;
   const normalizedNext = { ...next };
   const isClearingRowGrouping = nextState?.groupRowsBy !== void 0 && String(nextState.groupRowsBy ?? "").trim().length === 0;
@@ -62056,6 +62126,29 @@ function processPivotState(next, options = {}) {
     normalizedNext.aggregationState = [{ aggregationType: "count" }];
     normalizedNext.aggregationTablesByIndex = [void 0];
   }
+  if (!resolvedRowField) {
+    normalizedNext.aggregationState = normalizedNext.aggregationState.map(
+      (aggregation, index) => {
+        if (String(aggregation.aggregationType ?? "").toLowerCase() !== "percentage") {
+          return aggregation;
+        }
+        const valueField = String(aggregation.valueField ?? "").trim();
+        if (!valueField) {
+          return { ...aggregation, aggregationType: "count" };
+        }
+        const valueField2 = String(aggregation.valueField2 ?? "").trim();
+        if (valueField2 && valueField2 !== valueField) {
+          return aggregation;
+        }
+        const table = String(aggregation.valueFieldTable ?? "").trim() || String(normalizedNext.aggregationTablesByIndex[index] ?? "").trim() || void 0;
+        const isBool = isBoolAggregationField?.(valueField, table);
+        if (isBool === false) {
+          return { ...aggregation, aggregationType: "sum" };
+        }
+        return aggregation;
+      }
+    );
+  }
   if (isSettingRowGrouping && normalizedNext.aggregationState.length > 0) {
     normalizedNext.aggregationState = [...normalizedNext.aggregationState];
   }
@@ -63310,6 +63403,19 @@ function useReport(reportIdArg, options = {}) {
   const customFieldsRef = (0, import_react62.useRef)(schemaData.customFields);
   schemaForReportBuilderStateRef.current = schemaForReportBuilderState;
   customFieldsRef.current = schemaData.customFields;
+  const isBoolAggregationField = (0, import_react62.useCallback)(
+    (field, table2) => {
+      const fieldType = resolveFieldType({
+        field,
+        table: table2,
+        schemaTables: schemaForReportBuilderStateRef.current
+      });
+      if (!fieldType) return void 0;
+      const normalized = String(fieldType).trim().toLowerCase();
+      return isBoolType(normalized) || normalized === "boolean";
+    },
+    []
+  );
   const schemaForeignKeyMap = (0, import_react62.useMemo)(
     () => getSchemaForeignKeyMapping(schemaForReportBuilderState),
     [schemaForReportBuilderState]
@@ -64217,9 +64323,10 @@ function useReport(reportIdArg, options = {}) {
     const explicitTable = getPivotGroupOptionTable(targetRaw);
     const field = explicitTable ? decodePivotGroupOptionValue(targetRaw) : targetRaw;
     if (!field) return {};
+    const fieldForTableResolution = field.includes(":") ? String(field.split(":")[0] ?? "").trim() : field;
     const table2 = explicitTable ?? optionTableLookup.get(rawValue) ?? resolveFieldTable({
       report: sourceReport,
-      field,
+      field: fieldForTableResolution,
       schemaTables: schemaForReportBuilderState,
       preferredTables
     }) ?? void 0;
@@ -64234,7 +64341,19 @@ function useReport(reportIdArg, options = {}) {
     if (target === "table") {
       return table2 ? { table: table2 } : preferredTables[0] ? { table: preferredTables[0] } : {};
     }
-    if (aggregationType !== "count") {
+    if (aggregationType === "percentage" && target.includes(":")) {
+      const [numeratorRaw, denominatorRaw] = target.split(":");
+      const numerator = String(numeratorRaw ?? "").trim();
+      const denominator = String(denominatorRaw ?? "").trim();
+      if (numerator && denominator) {
+        return {
+          valueField: numerator,
+          valueField2: denominator,
+          ...table2 ? { table: table2 } : {}
+        };
+      }
+    }
+    if (aggregationType !== "count" && aggregationType !== "percentage") {
       return {
         valueField: target,
         ...table2 ? { table: table2 } : {}
@@ -64418,7 +64537,9 @@ function useReport(reportIdArg, options = {}) {
         const pivotAggregationsFromSource = Array.isArray(sourceReport.pivot?.aggregations) ? sourceReport.pivot.aggregations : sourceReport.pivot?.aggregationType ? [
           {
             valueField: sourceReport.pivot?.valueField,
+            valueFieldType: sourceReport.pivot?.valueFieldType,
             valueField2: sourceReport.pivot?.valueField2,
+            valueField2Type: sourceReport.pivot?.valueField2Type,
             aggregationType: sourceReport.pivot?.aggregationType
           }
         ] : [];
@@ -64503,7 +64624,8 @@ function useReport(reportIdArg, options = {}) {
           chartType: prev.chartType ?? sourceReport.chartType
         };
         const normalized = processPivotState(nextFromSource, {
-          promoteColumnToRow: shouldPromoteColumnToRowFromPendingFlag
+          promoteColumnToRow: shouldPromoteColumnToRowFromPendingFlag,
+          isBoolAggregationField
         });
         return normalized;
       }
@@ -64843,6 +64965,10 @@ function useReport(reportIdArg, options = {}) {
         aggregation.valueField,
         aggregationTablesByIndex[index]
       );
+      appendPivotColumn(
+        aggregation.valueField2,
+        aggregationTablesByIndex[index]
+      );
     });
     const joinColumns = getJoinColumnsFromTables(effectiveReportBuilderTables);
     const useWideTableColumns = expandReportBuilderColumnsForFlatTable && !pivotState && String(chartType ?? "").toLowerCase() === "table";
@@ -65172,9 +65298,13 @@ function useReport(reportIdArg, options = {}) {
       const aggregationType = String(aggregation.aggregationType);
       const normalizedAggregationType = aggregationType.toLowerCase();
       const tableHint = String(aggregationTablesByIndex[index] ?? "").trim();
-      const target = aggregation.valueField && aggregation.valueField.trim().length > 0 ? aggregation.valueField : normalizedAggregationType === "count" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
+      const valueField = String(aggregation.valueField ?? "").trim();
+      const valueField2 = String(aggregation.valueField2 ?? "").trim();
+      const isPercentageRatio = normalizedAggregationType === "percentage" && Boolean(valueField) && Boolean(valueField2);
+      const target = isPercentageRatio ? `${valueField}:${valueField2}` : valueField ? valueField : normalizedAggregationType === "count" || normalizedAggregationType === "percentage" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
+      const isBoolPercentage = normalizedAggregationType === "percentage" && Boolean(valueField) && isBoolAggregationField(valueField, tableHint || void 0) === true;
       return {
-        label: `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(target)}`,
+        label: isPercentageRatio ? `Percent ${toTitleCaseLabel(valueField)} of ${toTitleCaseLabel(valueField2)}` : normalizedAggregationType === "percentage" ? isBoolPercentage ? `Percent ${toTitleCaseLabel(target)}` : `Percent of Total ${toTitleCaseLabel(target)}` : `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(target)}`,
         value: `${aggregationType}:${target}`
       };
     });
@@ -65182,7 +65312,8 @@ function useReport(reportIdArg, options = {}) {
     aggregationFallbackTableName,
     aggregationFallbackTarget,
     aggregationState,
-    aggregationTablesByIndex
+    aggregationTablesByIndex,
+    isBoolAggregationField
   ]);
   const { aggregationBaseOptions, aggregationOptionTableLookup } = (0, import_react62.useMemo)(() => {
     const joinScoped = fieldOptionsAllowedTableNames ? joinCompatibleSchemaTableNames.filter(
@@ -65208,17 +65339,34 @@ function useReport(reportIdArg, options = {}) {
       if (tableName && !tableLookup.has(countValue)) {
         tableLookup.set(countValue, tableName);
       }
+      if (resolvedGroupRowsBy) {
+        const percentageValue = `percentage:${countTarget}`;
+        if (!seen.has(percentageValue)) {
+          options2.push({
+            value: percentageValue,
+            label: `Percent of Total ${toTitleCaseLabel(countTarget)}`
+          });
+          seen.add(percentageValue);
+        }
+        if (tableName && !tableLookup.has(percentageValue)) {
+          tableLookup.set(percentageValue, tableName);
+        }
+      }
       for (const column of table2.columns ?? []) {
         const fieldName = String(column.field ?? "").trim();
         if (!fieldName) continue;
+        const isBoolColumn = isBoolType(String(column.fieldType ?? "").toLowerCase()) || String(column.jsType ?? "").toLowerCase() === "boolean";
         for (const aggregationType of AGGREGATION_OPTION_TYPES) {
           if (aggregationType === "count") continue;
           if (!canAggregateColumn(column, aggregationType)) continue;
+          const isNumberSharePercentage = aggregationType === "percentage" && !isBoolColumn;
+          if (isNumberSharePercentage && !resolvedGroupRowsBy) continue;
           const value = `${aggregationType}:${fieldName}`;
           if (seen.has(value)) continue;
+          const aggregationWord = aggregationType === "percentage" ? isBoolColumn ? "Percent" : "Percent of Total" : formatAggregationTypeForDisplay(aggregationType);
           options2.push({
             value,
-            label: tableName ? `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(tableName)} ${toTitleCaseLabel(fieldName)}` : `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(fieldName)}`
+            label: tableName ? `${aggregationWord} ${toTitleCaseLabel(tableName)} ${toTitleCaseLabel(fieldName)}` : `${aggregationWord} ${toTitleCaseLabel(fieldName)}`
           });
           seen.add(value);
           if (tableName && !tableLookup.has(value)) {
@@ -65241,6 +65389,7 @@ function useReport(reportIdArg, options = {}) {
     cleanedAggregations,
     fieldOptionsAllowedTableNames,
     joinCompatibleSchemaTableNames,
+    resolvedGroupRowsBy,
     schemaForReportBuilderState
   ]);
   const { schemaColumnOptions, columnIdentifierLookup } = (0, import_react62.useMemo)(() => {
@@ -65483,9 +65632,13 @@ function useReport(reportIdArg, options = {}) {
         aggregation.aggregationType ?? ""
       ).toLowerCase();
       const tableHint = String(aggregationTablesByIndex[index] ?? "").trim();
-      const currentTarget = aggregation.valueField && aggregation.valueField.trim().length > 0 ? aggregation.valueField : normalizedAggregationType === "count" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
+      const currentValueField = String(aggregation.valueField ?? "").trim();
+      const currentValueField2 = String(aggregation.valueField2 ?? "").trim();
+      const isPercentageRatio = normalizedAggregationType === "percentage" && Boolean(currentValueField) && Boolean(currentValueField2);
+      const currentTarget = isPercentageRatio ? `${currentValueField}:${currentValueField2}` : currentValueField ? currentValueField : normalizedAggregationType === "count" || normalizedAggregationType === "percentage" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
       const currentValue = aggregation.aggregationType ? `${aggregation.aggregationType}:${currentTarget}` : void 0;
-      const currentLabel = aggregation.aggregationType ? `${formatAggregationTypeForDisplay(aggregation.aggregationType)} ${toTitleCaseLabel(currentTarget)}` : "Select aggregation";
+      const isBoolPercentage = normalizedAggregationType === "percentage" && Boolean(currentValueField) && isBoolAggregationField(currentValueField, tableHint || void 0) === true;
+      const currentLabel = aggregation.aggregationType ? isPercentageRatio ? `Percent ${toTitleCaseLabel(currentValueField)} of ${toTitleCaseLabel(currentValueField2)}` : normalizedAggregationType === "percentage" ? isBoolPercentage ? `Percent ${toTitleCaseLabel(currentTarget)}` : `Percent of Total ${toTitleCaseLabel(currentTarget)}` : `${formatAggregationTypeForDisplay(aggregation.aggregationType)} ${toTitleCaseLabel(currentTarget)}` : "Select aggregation";
       const options2 = currentValue ? baseOptions.some((option) => option.value === currentValue) ? baseOptions : [{ value: currentValue, label: currentLabel }, ...baseOptions] : baseOptions;
       return {
         key: `aggregation-${index}`,
@@ -65499,7 +65652,8 @@ function useReport(reportIdArg, options = {}) {
     aggregationFallbackTarget,
     aggregationState,
     aggregationBaseOptions,
-    aggregationTablesByIndex
+    aggregationTablesByIndex,
+    isBoolAggregationField
   ]);
   const nextPivot = (0, import_react62.useMemo)(() => {
     if (!sourceReport) return null;
@@ -67272,10 +67426,12 @@ function useReport(reportIdArg, options = {}) {
                   preferredTables
                 );
                 const existing = next.aggregationState[index];
+                const preservedValueField2 = aggregationType !== "percentage" && existing?.valueField2 ? { valueField2: existing.valueField2 } : {};
                 const nextAggregation = {
-                  ...existing?.valueField2 ? { valueField2: existing.valueField2 } : {},
+                  ...preservedValueField2,
                   aggregationType,
                   ...normalizedSelection.valueField ? { valueField: normalizedSelection.valueField } : {},
+                  ...normalizedSelection.valueField2 ? { valueField2: normalizedSelection.valueField2 } : {},
                   ...normalizedSelection.table ? { valueFieldTable: normalizedSelection.table } : {}
                 };
                 if (index === next.aggregationState.length) {
@@ -67312,6 +67468,7 @@ function useReport(reportIdArg, options = {}) {
                 {
                   aggregationType,
                   ...normalizedSelection.valueField ? { valueField: normalizedSelection.valueField } : {},
+                  ...normalizedSelection.valueField2 ? { valueField2: normalizedSelection.valueField2 } : {},
                   ...normalizedSelection.table ? { valueFieldTable: normalizedSelection.table } : {}
                 }
               ];
@@ -67436,7 +67593,8 @@ function useReport(reportIdArg, options = {}) {
           next.chartType = effectiveNextState.chartType || void 0;
         const normalizedNext = processPivotState(next, {
           nextState: effectiveNextState,
-          promoteColumnToRow: false
+          promoteColumnToRow: false,
+          isBoolAggregationField
         });
         return normalizedNext;
       }

package/dist/index.d.cts

@@ -2972,7 +2972,9 @@ type SetReportTableColumnSidebarPatch = {
 };
 type AggregationStateItem = Partial<{
     valueField: string;
+    valueFieldType: string;
     valueField2?: string;
+    valueField2Type?: string;
     aggregationType: AggregationType;
     /** Resolved datasource table for `valueField` (mirrors `aggregationTablesByIndex`). */
     valueFieldTable?: string;
@@ -3268,7 +3270,9 @@ declare function useReport(reportIdArg?: string, options?: UseReportOptions): {
     groupColumnsByOptions: SelectOption[];
     aggregations: Partial<{
         valueField: string;
+        valueFieldType: string;
         valueField2?: string;
+        valueField2Type?: string;
         aggregationType: AggregationType;
         /** Resolved datasource table for `valueField` (mirrors `aggregationTablesByIndex`). */
         valueFieldTable?: string;

package/dist/index.d.ts

@@ -2972,7 +2972,9 @@ type SetReportTableColumnSidebarPatch = {
 };
 type AggregationStateItem = Partial<{
     valueField: string;
+    valueFieldType: string;
     valueField2?: string;
+    valueField2Type?: string;
     aggregationType: AggregationType;
     /** Resolved datasource table for `valueField` (mirrors `aggregationTablesByIndex`). */
     valueFieldTable?: string;
@@ -3268,7 +3270,9 @@ declare function useReport(reportIdArg?: string, options?: UseReportOptions): {
     groupColumnsByOptions: SelectOption[];
     aggregations: Partial<{
         valueField: string;
+        valueFieldType: string;
         valueField2?: string;
+        valueField2Type?: string;
         aggregationType: AggregationType;
         /** Resolved datasource table for `valueField` (mirrors `aggregationTablesByIndex`). */
         valueFieldTable?: string;

package/dist/index.js

@@ -15162,11 +15162,11 @@ function isValidPivot(pivot) {
       reason: 'Value field cannot be empty when aggregation is not "count" or "percentage"'
     };
   } else if (pivot.aggregations?.some(
-    (a) => a.aggregationType === "percentage" && !a.valueField && (!pivot.rowField || pivot.columnField)
+    (a) => a.aggregationType === "percentage" && !a.valueField && !pivot.rowField
   )) {
     return {
       valid: false,
-      reason: "Empty percentage field only supported for pivot tables with a row field and no column field"
+      reason: "Empty percentage field only supported for pivot tables with a row field"
     };
   }
   return { valid: true, reason: "" };
@@ -16449,7 +16449,7 @@ function formatAggregationTypeForDisplay(aggregationType) {
     case "max":
       return "Max";
     case "percentage":
-      return "Percentage";
+      return "Percent";
     default:
       return aggregationType ? capitalize(String(aggregationType)) : "Value";
   }
@@ -16491,6 +16491,21 @@ function getDefaultPivotMeasureLabel(report) {
     return pivot.columnField ? "Count" : `Count ${snakeAndCamelCaseToTitleCase(tableNames[0] ?? "table")}`;
   }
   const target = valueField !== void 0 && String(valueField).trim() ? resolveValueFieldDisplayLabel(report, valueField) : tableNames.length > 0 ? tableNames.map((n) => snakeAndCamelCaseToTitleCase(n)).join(", ") : "table";
+  if (aggregationType.toLowerCase() === "percentage") {
+    const valueField2 = String(
+      fromAggregations?.valueField2 ?? ""
+    ).trim();
+    if (valueField && valueField2) {
+      return `Percent ${target} of ${resolveValueFieldDisplayLabel(report, valueField2)}`;
+    }
+    const valueFieldType = String(
+      fromAggregations?.valueFieldType ?? ""
+    ).trim().toLowerCase();
+    if (valueField && valueFieldType === "bool") {
+      return `Percent ${target}`;
+    }
+    return `Percent of Total ${target}`;
+  }
   return target ? `${aggWord} ${target}` : aggWord;
 }
 function humanizeLegacyPivotMeasureLabelFragment(text) {
@@ -16498,7 +16513,10 @@ function humanizeLegacyPivotMeasureLabelFragment(text) {
   if (!t) return t;
   const m = t.match(LEGACY_AGG_SNAKE_FIELD);
   if (!m) return t;
-  return `${formatAggregationTypeForDisplay(m[1])} ${snakeAndCamelCaseToTitleCase(m[2])}`;
+  if (String(m[1]).toLowerCase() === "percentage") {
+    return `Percent of Total ${snakeAndCamelCaseToTitleCase(m[2] ?? "")}`;
+  }
+  return `${formatAggregationTypeForDisplay(m[1])} ${snakeAndCamelCaseToTitleCase(m[2] ?? "")}`;
 }
 function humanizeChartSeriesTooltipLabel(label) {
   const s = String(label ?? "").trim();
@@ -60055,7 +60073,8 @@ var AGGREGATION_OPTION_TYPES = [
   "average",
   "count",
   "max",
-  "min"
+  "min",
+  "percentage"
 ];
 var QUERY_BUILDER_MULTI_VALUE_OPERATORS = /* @__PURE__ */ new Set(["in", "notin"]);
 var TABLE_FORMAT_CACHE_MAX_ENTRIES = 5e3;
@@ -60545,9 +60564,31 @@ function buildPivotAggregationsWithFieldTables({
       schemaTables,
       preferredTables
     }) || void 0;
+    const isPercentageAggregation = String(aggregation.aggregationType ?? "").toLowerCase() === "percentage";
+    const typeFallbackColumns = [
+      ...sourceReport?.columnInternal ?? sourceReport?.columns ?? []
+    ];
+    const valueFieldType = String(
+      aggregation.valueFieldType ?? ""
+    ).trim() || (isPercentageAggregation ? resolveFieldType({
+      field: aggregation.valueField,
+      table: valueFieldTable,
+      schemaTables,
+      fallbackColumns: typeFallbackColumns
+    }) : void 0);
+    const valueField2Type = String(
+      aggregation.valueField2Type ?? ""
+    ).trim() || (isPercentageAggregation ? resolveFieldType({
+      field: aggregation.valueField2,
+      table: valueFieldTable,
+      schemaTables,
+      fallbackColumns: typeFallbackColumns
+    }) : void 0);
     result.push({
       ...aggregationWithoutPivotTables,
       aggregationType: aggregation.aggregationType,
+      ...valueFieldType ? { valueFieldType } : {},
+      ...valueField2Type ? { valueField2Type } : {},
       ...valueFieldTable ? { valueFieldTable } : {}
     });
   }
@@ -60591,8 +60632,9 @@ function getPivotAggregationSortFields(aggregationState, resolvedColumnField) {
     const aggregationType = String(aggregation.aggregationType ?? "").trim();
     if (!aggregationType) continue;
     const valueField = String(aggregation.valueField ?? "").trim();
-    const canonicalBaseField = valueField || "count";
-    const sortField = hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
+    const isValuelessPercentage = !valueField && aggregationType.toLowerCase() === "percentage";
+    const canonicalBaseField = valueField || (isValuelessPercentage ? "percentage" : "count");
+    const sortField = isValuelessPercentage ? "percentage" : hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
     if (!seen.has(sortField)) {
       seen.add(sortField);
       fields.push(sortField);
@@ -60611,8 +60653,9 @@ function getPivotAggregationSortLabelOverrides(aggregationState, aggregationTabl
     const aggregationType = String(aggregation.aggregationType ?? "").trim();
     if (!aggregationType) continue;
     const valueField = String(aggregation.valueField ?? "").trim();
-    const canonicalBaseField = valueField || "count";
-    const sortField = hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
+    const isValuelessPercentage = !valueField && aggregationType.toLowerCase() === "percentage";
+    const canonicalBaseField = valueField || (isValuelessPercentage ? "percentage" : "count");
+    const sortField = isValuelessPercentage ? "percentage" : hasMultipleAggregations && aggregationType.toLowerCase() !== "count" ? `${canonicalBaseField}_${aggregationType}` : canonicalBaseField;
     if (labelBySortField.has(sortField)) continue;
     if (valueField || aggregationType.toLowerCase() !== "count") continue;
     const tableHint = String(aggregationTablesByIndex[index] ?? "").trim();
@@ -60766,6 +60809,9 @@ function trimAggregationSuffix(value, aggregationType) {
 }
 function getAggregationFieldKey(aggregation, hasMultipleAggregations) {
   if (!aggregation.aggregationType) return null;
+  if (!aggregation.valueField && aggregation.aggregationType === "percentage") {
+    return "percentage";
+  }
   if (aggregation.valueField) {
     return hasMultipleAggregations ? `${aggregation.valueField}_${aggregation.aggregationType}` : aggregation.valueField;
   }
@@ -60886,6 +60932,22 @@ function buildAggregationLabel(aggregation, report) {
   }
   const rawTarget = aggregation.valueField ?? (tableNames.length > 0 ? tableNames.join(", ") : "table");
   const target = report ? aggregation.valueField ? resolveValueFieldDisplayLabel(report, aggregation.valueField) : rawTarget : rawTarget;
+  if (String(aggregationType).toLowerCase() === "percentage") {
+    const valueField2 = String(
+      aggregation.valueField2 ?? ""
+    ).trim();
+    if (aggregation.valueField && valueField2) {
+      const denominator = report ? resolveValueFieldDisplayLabel(report, valueField2) : valueField2;
+      return `Percent ${target} of ${denominator}`;
+    }
+    const valueFieldType = String(
+      aggregation.valueFieldType ?? ""
+    ).trim().toLowerCase();
+    if (aggregation.valueField && valueFieldType === "bool") {
+      return `Percent ${target}`;
+    }
+    return `Percent of Total ${target}`;
+  }
   return target ? `${aggWord} ${target}` : aggWord;
 }
 function normalizePivotColumnDisplayValue(value) {
@@ -61025,6 +61087,13 @@ function normalizePivotChartForDisplay(chart) {
     if (aggregation?.aggregationType === "count") {
       return "whole_number";
     }
+    if (aggregation?.aggregationType === "percentage") {
+      const savedFormat = yAxisFormatByField.get(field);
+      if (savedFormat === "percent" || savedFormat === "percentage") {
+        return savedFormat;
+      }
+      return "percentage";
+    }
     const directAxisFormat = yAxisFormatByField.get(field);
     if (directAxisFormat) return directAxisFormat;
     const aggType = aggregation?.aggregationType ? String(aggregation.aggregationType) : void 0;
@@ -62221,7 +62290,8 @@ function processPivotState(next, options = {}) {
   const {
     nextState,
     promoteColumnToRow = false,
-    fallbackColumnGroupBy
+    fallbackColumnGroupBy,
+    isBoolAggregationField
   } = options;
   const normalizedNext = { ...next };
   const isClearingRowGrouping = nextState?.groupRowsBy !== void 0 && String(nextState.groupRowsBy ?? "").trim().length === 0;
@@ -62264,6 +62334,29 @@ function processPivotState(next, options = {}) {
     normalizedNext.aggregationState = [{ aggregationType: "count" }];
     normalizedNext.aggregationTablesByIndex = [void 0];
   }
+  if (!resolvedRowField) {
+    normalizedNext.aggregationState = normalizedNext.aggregationState.map(
+      (aggregation, index) => {
+        if (String(aggregation.aggregationType ?? "").toLowerCase() !== "percentage") {
+          return aggregation;
+        }
+        const valueField = String(aggregation.valueField ?? "").trim();
+        if (!valueField) {
+          return { ...aggregation, aggregationType: "count" };
+        }
+        const valueField2 = String(aggregation.valueField2 ?? "").trim();
+        if (valueField2 && valueField2 !== valueField) {
+          return aggregation;
+        }
+        const table = String(aggregation.valueFieldTable ?? "").trim() || String(normalizedNext.aggregationTablesByIndex[index] ?? "").trim() || void 0;
+        const isBool = isBoolAggregationField?.(valueField, table);
+        if (isBool === false) {
+          return { ...aggregation, aggregationType: "sum" };
+        }
+        return aggregation;
+      }
+    );
+  }
   if (isSettingRowGrouping && normalizedNext.aggregationState.length > 0) {
     normalizedNext.aggregationState = [...normalizedNext.aggregationState];
   }
@@ -63518,6 +63611,19 @@ function useReport(reportIdArg, options = {}) {
   const customFieldsRef = useRef25(schemaData.customFields);
   schemaForReportBuilderStateRef.current = schemaForReportBuilderState;
   customFieldsRef.current = schemaData.customFields;
+  const isBoolAggregationField = useCallback6(
+    (field, table2) => {
+      const fieldType = resolveFieldType({
+        field,
+        table: table2,
+        schemaTables: schemaForReportBuilderStateRef.current
+      });
+      if (!fieldType) return void 0;
+      const normalized = String(fieldType).trim().toLowerCase();
+      return isBoolType(normalized) || normalized === "boolean";
+    },
+    []
+  );
   const schemaForeignKeyMap = useMemo33(
     () => getSchemaForeignKeyMapping(schemaForReportBuilderState),
     [schemaForReportBuilderState]
@@ -64425,9 +64531,10 @@ function useReport(reportIdArg, options = {}) {
     const explicitTable = getPivotGroupOptionTable(targetRaw);
     const field = explicitTable ? decodePivotGroupOptionValue(targetRaw) : targetRaw;
     if (!field) return {};
+    const fieldForTableResolution = field.includes(":") ? String(field.split(":")[0] ?? "").trim() : field;
     const table2 = explicitTable ?? optionTableLookup.get(rawValue) ?? resolveFieldTable({
       report: sourceReport,
-      field,
+      field: fieldForTableResolution,
       schemaTables: schemaForReportBuilderState,
       preferredTables
     }) ?? void 0;
@@ -64442,7 +64549,19 @@ function useReport(reportIdArg, options = {}) {
     if (target === "table") {
       return table2 ? { table: table2 } : preferredTables[0] ? { table: preferredTables[0] } : {};
     }
-    if (aggregationType !== "count") {
+    if (aggregationType === "percentage" && target.includes(":")) {
+      const [numeratorRaw, denominatorRaw] = target.split(":");
+      const numerator = String(numeratorRaw ?? "").trim();
+      const denominator = String(denominatorRaw ?? "").trim();
+      if (numerator && denominator) {
+        return {
+          valueField: numerator,
+          valueField2: denominator,
+          ...table2 ? { table: table2 } : {}
+        };
+      }
+    }
+    if (aggregationType !== "count" && aggregationType !== "percentage") {
       return {
         valueField: target,
         ...table2 ? { table: table2 } : {}
@@ -64626,7 +64745,9 @@ function useReport(reportIdArg, options = {}) {
         const pivotAggregationsFromSource = Array.isArray(sourceReport.pivot?.aggregations) ? sourceReport.pivot.aggregations : sourceReport.pivot?.aggregationType ? [
           {
             valueField: sourceReport.pivot?.valueField,
+            valueFieldType: sourceReport.pivot?.valueFieldType,
             valueField2: sourceReport.pivot?.valueField2,
+            valueField2Type: sourceReport.pivot?.valueField2Type,
             aggregationType: sourceReport.pivot?.aggregationType
           }
         ] : [];
@@ -64711,7 +64832,8 @@ function useReport(reportIdArg, options = {}) {
           chartType: prev.chartType ?? sourceReport.chartType
         };
         const normalized = processPivotState(nextFromSource, {
-          promoteColumnToRow: shouldPromoteColumnToRowFromPendingFlag
+          promoteColumnToRow: shouldPromoteColumnToRowFromPendingFlag,
+          isBoolAggregationField
         });
         return normalized;
       }
@@ -65051,6 +65173,10 @@ function useReport(reportIdArg, options = {}) {
         aggregation.valueField,
         aggregationTablesByIndex[index]
       );
+      appendPivotColumn(
+        aggregation.valueField2,
+        aggregationTablesByIndex[index]
+      );
     });
     const joinColumns = getJoinColumnsFromTables(effectiveReportBuilderTables);
     const useWideTableColumns = expandReportBuilderColumnsForFlatTable && !pivotState && String(chartType ?? "").toLowerCase() === "table";
@@ -65380,9 +65506,13 @@ function useReport(reportIdArg, options = {}) {
       const aggregationType = String(aggregation.aggregationType);
       const normalizedAggregationType = aggregationType.toLowerCase();
       const tableHint = String(aggregationTablesByIndex[index] ?? "").trim();
-      const target = aggregation.valueField && aggregation.valueField.trim().length > 0 ? aggregation.valueField : normalizedAggregationType === "count" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
+      const valueField = String(aggregation.valueField ?? "").trim();
+      const valueField2 = String(aggregation.valueField2 ?? "").trim();
+      const isPercentageRatio = normalizedAggregationType === "percentage" && Boolean(valueField) && Boolean(valueField2);
+      const target = isPercentageRatio ? `${valueField}:${valueField2}` : valueField ? valueField : normalizedAggregationType === "count" || normalizedAggregationType === "percentage" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
+      const isBoolPercentage = normalizedAggregationType === "percentage" && Boolean(valueField) && isBoolAggregationField(valueField, tableHint || void 0) === true;
       return {
-        label: `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(target)}`,
+        label: isPercentageRatio ? `Percent ${toTitleCaseLabel(valueField)} of ${toTitleCaseLabel(valueField2)}` : normalizedAggregationType === "percentage" ? isBoolPercentage ? `Percent ${toTitleCaseLabel(target)}` : `Percent of Total ${toTitleCaseLabel(target)}` : `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(target)}`,
         value: `${aggregationType}:${target}`
       };
     });
@@ -65390,7 +65520,8 @@ function useReport(reportIdArg, options = {}) {
     aggregationFallbackTableName,
     aggregationFallbackTarget,
     aggregationState,
-    aggregationTablesByIndex
+    aggregationTablesByIndex,
+    isBoolAggregationField
   ]);
   const { aggregationBaseOptions, aggregationOptionTableLookup } = useMemo33(() => {
     const joinScoped = fieldOptionsAllowedTableNames ? joinCompatibleSchemaTableNames.filter(
@@ -65416,17 +65547,34 @@ function useReport(reportIdArg, options = {}) {
       if (tableName && !tableLookup.has(countValue)) {
         tableLookup.set(countValue, tableName);
       }
+      if (resolvedGroupRowsBy) {
+        const percentageValue = `percentage:${countTarget}`;
+        if (!seen.has(percentageValue)) {
+          options2.push({
+            value: percentageValue,
+            label: `Percent of Total ${toTitleCaseLabel(countTarget)}`
+          });
+          seen.add(percentageValue);
+        }
+        if (tableName && !tableLookup.has(percentageValue)) {
+          tableLookup.set(percentageValue, tableName);
+        }
+      }
       for (const column of table2.columns ?? []) {
         const fieldName = String(column.field ?? "").trim();
         if (!fieldName) continue;
+        const isBoolColumn = isBoolType(String(column.fieldType ?? "").toLowerCase()) || String(column.jsType ?? "").toLowerCase() === "boolean";
         for (const aggregationType of AGGREGATION_OPTION_TYPES) {
           if (aggregationType === "count") continue;
           if (!canAggregateColumn(column, aggregationType)) continue;
+          const isNumberSharePercentage = aggregationType === "percentage" && !isBoolColumn;
+          if (isNumberSharePercentage && !resolvedGroupRowsBy) continue;
           const value = `${aggregationType}:${fieldName}`;
           if (seen.has(value)) continue;
+          const aggregationWord = aggregationType === "percentage" ? isBoolColumn ? "Percent" : "Percent of Total" : formatAggregationTypeForDisplay(aggregationType);
           options2.push({
             value,
-            label: tableName ? `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(tableName)} ${toTitleCaseLabel(fieldName)}` : `${formatAggregationTypeForDisplay(aggregationType)} ${toTitleCaseLabel(fieldName)}`
+            label: tableName ? `${aggregationWord} ${toTitleCaseLabel(tableName)} ${toTitleCaseLabel(fieldName)}` : `${aggregationWord} ${toTitleCaseLabel(fieldName)}`
           });
           seen.add(value);
           if (tableName && !tableLookup.has(value)) {
@@ -65449,6 +65597,7 @@ function useReport(reportIdArg, options = {}) {
     cleanedAggregations,
     fieldOptionsAllowedTableNames,
     joinCompatibleSchemaTableNames,
+    resolvedGroupRowsBy,
     schemaForReportBuilderState
   ]);
   const { schemaColumnOptions, columnIdentifierLookup } = useMemo33(() => {
@@ -65691,9 +65840,13 @@ function useReport(reportIdArg, options = {}) {
         aggregation.aggregationType ?? ""
       ).toLowerCase();
       const tableHint = String(aggregationTablesByIndex[index] ?? "").trim();
-      const currentTarget = aggregation.valueField && aggregation.valueField.trim().length > 0 ? aggregation.valueField : normalizedAggregationType === "count" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
+      const currentValueField = String(aggregation.valueField ?? "").trim();
+      const currentValueField2 = String(aggregation.valueField2 ?? "").trim();
+      const isPercentageRatio = normalizedAggregationType === "percentage" && Boolean(currentValueField) && Boolean(currentValueField2);
+      const currentTarget = isPercentageRatio ? `${currentValueField}:${currentValueField2}` : currentValueField ? currentValueField : normalizedAggregationType === "count" || normalizedAggregationType === "percentage" ? tableHint || aggregationFallbackTableName : aggregationFallbackTarget;
       const currentValue = aggregation.aggregationType ? `${aggregation.aggregationType}:${currentTarget}` : void 0;
-      const currentLabel = aggregation.aggregationType ? `${formatAggregationTypeForDisplay(aggregation.aggregationType)} ${toTitleCaseLabel(currentTarget)}` : "Select aggregation";
+      const isBoolPercentage = normalizedAggregationType === "percentage" && Boolean(currentValueField) && isBoolAggregationField(currentValueField, tableHint || void 0) === true;
+      const currentLabel = aggregation.aggregationType ? isPercentageRatio ? `Percent ${toTitleCaseLabel(currentValueField)} of ${toTitleCaseLabel(currentValueField2)}` : normalizedAggregationType === "percentage" ? isBoolPercentage ? `Percent ${toTitleCaseLabel(currentTarget)}` : `Percent of Total ${toTitleCaseLabel(currentTarget)}` : `${formatAggregationTypeForDisplay(aggregation.aggregationType)} ${toTitleCaseLabel(currentTarget)}` : "Select aggregation";
       const options2 = currentValue ? baseOptions.some((option) => option.value === currentValue) ? baseOptions : [{ value: currentValue, label: currentLabel }, ...baseOptions] : baseOptions;
       return {
         key: `aggregation-${index}`,
@@ -65707,7 +65860,8 @@ function useReport(reportIdArg, options = {}) {
     aggregationFallbackTarget,
     aggregationState,
     aggregationBaseOptions,
-    aggregationTablesByIndex
+    aggregationTablesByIndex,
+    isBoolAggregationField
   ]);
   const nextPivot = useMemo33(() => {
     if (!sourceReport) return null;
@@ -67480,10 +67634,12 @@ function useReport(reportIdArg, options = {}) {
                   preferredTables
                 );
                 const existing = next.aggregationState[index];
+                const preservedValueField2 = aggregationType !== "percentage" && existing?.valueField2 ? { valueField2: existing.valueField2 } : {};
                 const nextAggregation = {
-                  ...existing?.valueField2 ? { valueField2: existing.valueField2 } : {},
+                  ...preservedValueField2,
                   aggregationType,
                   ...normalizedSelection.valueField ? { valueField: normalizedSelection.valueField } : {},
+                  ...normalizedSelection.valueField2 ? { valueField2: normalizedSelection.valueField2 } : {},
                   ...normalizedSelection.table ? { valueFieldTable: normalizedSelection.table } : {}
                 };
                 if (index === next.aggregationState.length) {
@@ -67520,6 +67676,7 @@ function useReport(reportIdArg, options = {}) {
                 {
                   aggregationType,
                   ...normalizedSelection.valueField ? { valueField: normalizedSelection.valueField } : {},
+                  ...normalizedSelection.valueField2 ? { valueField2: normalizedSelection.valueField2 } : {},
                   ...normalizedSelection.table ? { valueFieldTable: normalizedSelection.table } : {}
                 }
               ];
@@ -67644,7 +67801,8 @@ function useReport(reportIdArg, options = {}) {
           next.chartType = effectiveNextState.chartType || void 0;
         const normalizedNext = processPivotState(next, {
           nextState: effectiveNextState,
-          promoteColumnToRow: false
+          promoteColumnToRow: false,
+          isBoolAggregationField
         });
         return normalizedNext;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillsql/react",
-  "version": "2.16.46",
+  "version": "2.16.48",
   "type": "module",
   "exports": {
     ".": {