@altertable/data-app 0.67.0 → 0.68.0

package/dist/types/react/style-contract.d.ts

@@ -59,6 +59,18 @@ export declare const dataAppStyleClasses: {
         readonly component: 'ChartLegend.Label';
         readonly kind: 'root';
     };
+    readonly 'altertable-funnel-chart': {
+        readonly component: 'FunnelChart';
+        readonly kind: 'root';
+    };
+    readonly 'altertable-retention-chart': {
+        readonly component: 'RetentionChart';
+        readonly kind: 'root';
+    };
+    readonly 'altertable-journey-chart': {
+        readonly component: 'JourneyChart';
+        readonly kind: 'root';
+    };
     readonly 'altertable-composed-chart': {
         readonly component: 'ComposedChart';
         readonly kind: 'root';

package/dist/types/react/ui/ChartLegend.d.ts

@@ -14,7 +14,7 @@ export type ChartLegendItemProps = ComponentPropsWithRef<'li'> & {
 };
 /** Descriptive by default; compose a button inside the item for an authored series toggle. */
 declare function ChartLegendItem({ inactive, className, ...props }: ChartLegendItemProps): import("react").JSX.Element;
-export type ChartLegendMarkerKind = 'bar' | 'line' | 'area' | 'point' | 'slice';
+export type ChartLegendMarkerKind = 'square' | 'bar' | 'line' | 'area' | 'point' | 'slice';
 export type ChartLegendMarkerProps = Omit<ComponentPropsWithRef<'svg'>, 'children'> & {
     kind: ChartLegendMarkerKind;
 };

package/dist/types/react/ui/ComposedChart.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentProps } from 'react';
+import { type ComponentProps } from 'react';
 import { ComposedChartLegend as Legend } from './ComposedChartLegend.js';
 import { ComposedChart as RechartsComposedChart, ZAxis, ReferenceLine, ReferenceArea, ReferenceDot, Brush, Label, LabelList, ErrorBar } from 'recharts';
 import { ChartBar as Bar, ChartDot as Dot, ChartLine as Line, ChartArea as Area, ChartScatter as Scatter, ChartXAxis as XAxis, ChartYAxis as YAxis, ChartGrid as CartesianGrid, ChartTooltip as Tooltip } from './chart-primitives.js';

package/dist/types/react/ui/FunnelChart.d.ts

@@ -0,0 +1,20 @@
+import type { CountChartProps } from './chart-data.js';
+/** Ordered step with a unique, nonblank ID. */
+export type FunnelChartStep = {
+    id: string;
+    label: string;
+};
+export type FunnelChartSeries = {
+    /** Unique, nonblank population ID. */
+    id: string;
+    label: string;
+    /** Finite, nonnegative counts aligned with steps and nonincreasing. */
+    values: readonly number[];
+};
+export type FunnelChartProps = CountChartProps & {
+    steps: readonly FunnelChartStep[];
+    series: readonly FunnelChartSeries[];
+};
+/** Conversion columns with previous-step drop-off, normalized to each series' first step.
+ * Owns series highlighting and portion-specific inspection; compose inside VisualizationWidget. */
+export declare function FunnelChart({ steps, series, unit, ariaLabel, className, formatValue, }: FunnelChartProps): import("react").JSX.Element;

package/dist/types/react/ui/JourneyChart.d.ts

@@ -0,0 +1,10 @@
+import type { CountChartProps } from './chart-data.js';
+import { type JourneyChartPath } from './journey-flow.js';
+export type { JourneyChartPath } from './journey-flow.js';
+export type JourneyChartProps = CountChartProps & {
+    /** Full paths and their population counts. Branches and outcomes are derived internally. */
+    paths: readonly JourneyChartPath[];
+};
+/** Path exploration with two initial steps, expandable prefixes, and three events per depth.
+ * Counts and flows use the Step 1 population. Compose inside VisualizationWidget. */
+export declare function JourneyChart({ paths, unit, ariaLabel, className, formatValue, }: JourneyChartProps): import("react").JSX.Element;

package/dist/types/react/ui/RetentionChart.d.ts

@@ -0,0 +1,27 @@
+import type { CountChartProps } from './chart-data.js';
+export type RetentionChartPoint = {
+    /** Nonnegative integer, unique per series; uneven offsets retain their distance. */
+    offset: number;
+    /** Must agree across series for the same offset. */
+    label: string;
+    /** Observed retention fraction in [0, 1], or null for an unobserved period. */
+    rate: number | null;
+    /** Finite count in [0, cohortSize]; null exactly when rate is null. */
+    retainedCount: number | null;
+    /** Observed but still accumulating; drawn as a dotted tail. */
+    incomplete?: boolean;
+};
+export type RetentionChartSeries = {
+    /** Unique, nonblank cohort or segment ID. */
+    id: string;
+    label: string;
+    /** Finite, nonnegative starting population. */
+    cohortSize: number;
+    points: readonly RetentionChartPoint[];
+};
+export type RetentionChartProps = CountChartProps & {
+    series: readonly RetentionChartSeries[];
+};
+/** Query-defined retention curves with count inspection and dotted incomplete periods.
+ * Rates are not recomputed from counts. Compose inside VisualizationWidget. */
+export declare function RetentionChart({ series, unit, ariaLabel, className, formatValue, }: RetentionChartProps): import("react").JSX.Element;

package/dist/types/react/ui/chart-data.d.ts

@@ -11,6 +11,15 @@ export type ValueChartProps = {
     ariaLabel: string;
     formatValue?: (value: number) => string;
 };
+export type CountChartProps = {
+    /** Accessible measure and scope description. */
+    ariaLabel: string;
+    /** Population unit, such as users or sessions. */
+    unit: string;
+    /** Formats counts; rates use percentage formatting. */
+    formatValue?: (value: number) => string;
+    className?: string;
+};
 /** Independent observation on two finite numeric axes. */
 export type ScatterChartItem = {
     id: string;

package/dist/types/react/ui/chart-primitives.d.ts

@@ -1,6 +1,5 @@
 import type { ComponentProps } from 'react';
-import { type DotProps, Scatter, XAxis, YAxis, CartesianGrid, Tooltip, type BarProps, type LineProps, type AreaProps } from 'recharts';
-export declare const chartBarFill = "var(--atbl-chart-fill, color-mix(in srgb, var(--atbl-accent) 75%, var(--atbl-surface)))";
+import { type DotProps, Scatter, XAxis, YAxis, CartesianGrid, Tooltip, DefaultTooltipContent, type BarProps, type LineProps, type AreaProps } from 'recharts';
 /** Hollow sample marker shared by standalone and composed series. */
 export declare function ChartDot({ active, stroke, fill, r, ...props }: DotProps & {
     active?: boolean;
@@ -16,5 +15,8 @@ export declare function ChartScatter<Row = unknown, Value = number>(props: Compo
 export declare function ChartXAxis<Row = unknown, Value = string | number>(props: ComponentProps<typeof XAxis<Row, Value>>): import("react").JSX.Element;
 export declare function ChartYAxis<Row = unknown, Value = number>(props: ComponentProps<typeof YAxis<Row, Value>>): import("react").JSX.Element;
 export declare function ChartGrid(props: ComponentProps<typeof CartesianGrid>): import("react").JSX.Element;
+export declare function ChartTooltipContent(props: ComponentProps<typeof DefaultTooltipContent> & {
+    active?: boolean;
+}): import("react").JSX.Element | null;
 /** Uses the same surface as single-series inspection; Recharts owns interaction. */
 export declare function ChartTooltip(props: ComponentProps<typeof Tooltip>): import("react").JSX.Element;

package/dist/types/react/ui/chartColor.d.ts

@@ -1 +1,2 @@
 export declare function chartColor(id: string): string;
+export declare const chartBarFill = "var(--atbl-chart-fill, color-mix(in srgb, var(--atbl-accent) 75%, var(--atbl-surface)))";

package/dist/types/react/ui/index.d.ts

@@ -96,3 +96,10 @@ export type { ComposedChartProps } from './ComposedChart.js';
 export { ChartLegend } from './ChartLegend.js';
 export type { ChartLegendProps, ChartLegendItemProps, ChartLegendMarkerProps, ChartLegendLabelProps, ChartLegendMarkerKind, } from './ChartLegend.js';
 export type { ComposedChartLegendProps } from './ComposedChartLegend.js';
+export { FunnelChart } from './FunnelChart.js';
+export type { FunnelChartProps, FunnelChartStep, FunnelChartSeries, } from './FunnelChart.js';
+export { RetentionChart } from './RetentionChart.js';
+export type { RetentionChartProps, RetentionChartPoint, RetentionChartSeries, } from './RetentionChart.js';
+export { JourneyChart } from './JourneyChart.js';
+export type { JourneyChartProps, JourneyChartPath, } from './JourneyChart.js';
+export { useSvgId } from './useSvgId.js';

package/dist/types/react/ui/journey-flow.d.ts

@@ -0,0 +1,49 @@
+/** Aggregated route; repeated events remain distinct by depth and prefix. */
+export type JourneyChartPath = {
+    /** Unique, nonblank path ID. */
+    id: string;
+    /** At least one nonblank event; null property means no property grouping. */
+    steps: readonly {
+        event: string;
+        property: string | null;
+    }[];
+    /** Finite, nonnegative population following this route. */
+    count: number;
+    /** True: converted; false: dropped off; null: no conversion classification. */
+    converted: boolean | null;
+    /** Stops at the last loaded event, without adding an outcome or expand control. */
+    truncated: boolean;
+};
+export type JourneyNode = {
+    key: string;
+    label: string;
+    depth: number;
+    outcome: 'event' | 'converted' | 'drop-off' | 'truncated' | 'end' | 'other';
+    count: number;
+    pathKeys: string[];
+    branchKeys?: string[];
+    expandable?: boolean;
+    expanded?: boolean;
+    hiddenBranchCount?: number;
+};
+export declare function journeyNodes(path: JourneyChartPath): Omit<JourneyNode, 'count' | 'pathKeys'>[];
+export declare function buildJourneyFlow(paths: readonly JourneyChartPath[], expandedBranch?: string[]): {
+    nodes: JourneyNode[];
+    links: {
+        key: string;
+        source: string;
+        target: string;
+        count: number;
+        pathKeys: string[];
+    }[];
+};
+export declare function limitJourneyFlow(graph: ReturnType<typeof buildJourneyFlow>, visibleEventsByDepth?: Record<number, number>): {
+    nodes: JourneyNode[];
+    links: {
+        key: string;
+        source: string;
+        target: string;
+        count: number;
+        pathKeys: string[];
+    }[];
+};

package/dist/types/react/ui/useSvgId.d.ts

@@ -0,0 +1,2 @@
+/** Stable React ID for SVG definitions and their URL references; safe with identifier prefixes. */
+export declare function useSvgId(): string;

package/dist/worker.js

@@ -65,7 +65,7 @@ function trustedParent(config, searchParams) {
 }
 
 // src/worker/index.ts
-var TOKEN_RE = /^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)+-app-[1-9][0-9]*$/;
+var TOKEN_RE = /^(?=.{1,63}$)[a-z0-9]+(?:-+[a-z0-9]+)+$/;
 function isPreviewHost(hostname, domainName) {
   const suffix = `.${domainName}`;
   return hostname.endsWith(suffix) && TOKEN_RE.test(hostname.slice(0, -suffix.length));

package/docs/contract.md

@@ -11,7 +11,8 @@ import operation types using `import type`.
 Declare SQL once with `defineDataApp()` to preserve exact query and parameter
 names. Use stable `lowerCamelCase` IDs describing the result, such as `products`,
 `productsByCategory`, or `dailyRevenue`. Use plural names for row lists; keep parameter
-values in `params`.
+values in `params`. Every query must include `params`; use `{}` when it declares no
+parameters.
 The app owns an immutable registry snapshot. Define operations with
 `dataApp.defineOperation()`.
 

package/docs/ui.md

@@ -100,6 +100,22 @@ the samples. Pie slices represent mutually exclusive parts of one total; shares
 use the sum of supplied items, so include Other when showing a subset of the
 whole. Scatter points represent independent X/Y observations.
 
+Use `useSvgId()` for stable IDs when composing custom SVG definitions.
+
+### Product analytics charts
+
+Use `<FunnelChart>`, `<RetentionChart>`, and `<JourneyChart>` from `/react/ui`
+inside `<VisualizationWidget>`. Derive inputs from the displayed rows; the
+binding owns loading, evidence, CSV, and story content. Types and JSDoc describe
+input constraints; the gallery includes complete examples.
+
+- `<FunnelChart>` compares ordered step counts across populations. Each series
+  uses its first step as the baseline; hatching shows previous-step drop-off.
+- `<RetentionChart>` plots query-defined rates and retained counts by interval
+  offset. Use `null` for unobserved periods; `incomplete` produces a dotted tail.
+- `<JourneyChart>` derives expandable branches and outcomes from full paths.
+  Truncated paths stop at the last loaded event.
+
 ### Composed charts
 
 Use `<ComposedChart>` from `/react/ui` for multiple series or mixed marks inside
@@ -134,10 +150,12 @@ its columns aligned with the displayed measures.
 
 ### Legends
 
-Include `<ComposedChart.Legend />` to derive labels and markers from the series;
+Include `<ComposedChart.Legend />` to derive labels and colored square markers from the series;
 omit it when no legend is needed. For any chart, compose `<ChartLegend>` with
 `<ChartLegend.Item>`, `<ChartLegend.Marker>`, and `<ChartLegend.Label>` using the
-same names and colors as the plot.
+same names and colors as the plot. Square markers are
+shared with chart tooltips and funnel summaries. Pass `kind="square"` explicitly
+when composing a marker.
 `<PieChart>` includes a legend by default; `showLegend={false}` omits it.
 
 Legends align cells in a container-responsive grid, truncate labels, and reserve

package/docs/widgets.md

@@ -28,18 +28,21 @@ Choose the component by the reader's question. Compose dataset visuals inside
 charts come from `/react/ui`; `<Ranking>`, `<Breakdown>`, and `<Comparison>`
 are also available from `/react`.
 
-| Question or need                                          | Component         | Guidance                                                                                                           |
-| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
-| How do categories compare?                                | `<BarChart>`      | Compare nonnegative category values; order by value for rank or by a meaningful category order.                    |
-| Which items lead?                                         | `<Ranking>`       | Use a compact ordered list with values and optional detail. Tracks scale to the largest visible item, not a total. |
-| How does a measure change over time?                      | `<LineChart>`     | Use ordered, equally spaced samples to emphasize the trend.                                                        |
-| How large is the measure over time?                       | `<AreaChart>`     | Use the same samples as a line chart when filled magnitude relative to zero helps answer the question.             |
-| What makes up the whole?                                  | `<PieChart>`      | Use a few mutually exclusive parts of one total; include the remainder as Other.                                   |
-| What share of an observed total does each part represent? | `<Breakdown>`     | Use a compact display of values and shares with an explicit total, including when only some parts are shown.       |
-| How do several measures relate on one plot?               | `<ComposedChart>` | Compose bars, lines, areas, or scatter series; label units clearly and use separate axes for different units.      |
-| How are two numeric measures related?                     | `<ScatterChart>`  | Use independent X/Y observations to explore relationships, clusters, and outliers.                                 |
-| How did one metric change between periods?                | `<Comparison>`    | Use the metric reading and its displayed comparison period.                                                        |
-| What are the exact values or row details?                 | `<TableWidget>`   | Use a bound table for lookup, search, and precise comparisons.                                                     |
+| Question or need                                          | Component          | Guidance                                                                                                           |
+| --------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| How do categories compare?                                | `<BarChart>`       | Compare nonnegative category values; order by value for rank or by a meaningful category order.                    |
+| Which items lead?                                         | `<Ranking>`        | Use a compact ordered list with values and optional detail. Tracks scale to the largest visible item, not a total. |
+| How does a measure change over time?                      | `<LineChart>`      | Use ordered, equally spaced samples to emphasize the trend.                                                        |
+| How large is the measure over time?                       | `<AreaChart>`      | Use the same samples as a line chart when filled magnitude relative to zero helps answer the question.             |
+| What makes up the whole?                                  | `<PieChart>`       | Use a few mutually exclusive parts of one total; include the remainder as Other.                                   |
+| What share of an observed total does each part represent? | `<Breakdown>`      | Use a compact display of values and shares with an explicit total, including when only some parts are shown.       |
+| How do several measures relate on one plot?               | `<ComposedChart>`  | Compose bars, lines, areas, or scatter series; label units clearly and use separate axes for different units.      |
+| How are two numeric measures related?                     | `<ScatterChart>`   | Use independent X/Y observations to explore relationships, clusters, and outliers.                                 |
+| Where do users drop out of a sequence?                    | `<FunnelChart>`    | Use ordered counts from the same population reaching each successive step.                                         |
+| Do cohorts return over time?                              | `<RetentionChart>` | Use query-defined rates and retained counts by numeric offset; mark incomplete periods.                            |
+| Which paths do users take?                                | `<JourneyChart>`   | Use full paths with population counts and outcomes; explore branches step by step.                                 |
+| How did one metric change between periods?                | `<Comparison>`     | Use the metric reading and its displayed comparison period.                                                        |
+| What are the exact values or row details?                 | `<TableWidget>`    | Use a bound table for lookup, search, and precise comparisons.                                                     |
 
 Prefer bars or a ranking when readers need to compare similarly sized categories;
 use a pie for a simple composition question. Prefer a line when the trend is

package/docs/worker.md

@@ -28,7 +28,8 @@ and these string bindings:
 | `PARENT_ORIGINS` | Space-separated trusted HTTP(S) origins; first exact origin is the default | `https://app.example.com https://*.preview.example.com` |
 
 The Worker serves only `/` on a single preview label under `DOMAIN_NAME` matching
-`/^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)+-app-[1-9][0-9]*$/`. Other hosts and paths
+`/^(?=.{1,63}$)[a-z0-9]+(?:-+[a-z0-9]+)+$/`
+(any hyphenated lowercase DNS label; the host keeps each app's label unique). Other hosts and paths
 return 404. GET returns HTML; HEAD returns the same headers with no body. Other
 methods return 405 with `Allow: GET, HEAD`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altertable/data-app",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Contracts, transport, and React UI for Altertable data apps",
   "keywords": [
     "altertable",