create-yss-spec 1.1.2 → 1.1.3

package/template/.codex/skills/data-analytics/src/analytics-app/charting/chart-compatibility.ts

@@ -0,0 +1,164 @@
+import type { ChartSpec, ChartType } from "./chart-contract";
+import { asNumber, type ChartDataRow } from "./chart-transforms";
+import { CHART_TYPE_LABELS, CHART_TYPE_ORDER } from "./chart-theme";
+
+export type ChartTypeOption = {
+  label: string;
+  type: ChartType;
+};
+
+export type ChartTypeOptionSection = {
+  options: ChartTypeOption[];
+  title: string;
+};
+
+const CHART_TYPE_MENU_SECTIONS: Array<{ title: string; types: ChartType[] }> = [
+  {
+    title: "Trends",
+    types: ["line", "area", "stackedArea", "sparkline"],
+  },
+  {
+    title: "Comparison",
+    types: ["bar", "leaderboard"],
+  },
+  {
+    title: "Distribution",
+    types: ["histogram", "boxPlot"],
+  },
+  {
+    title: "Relationships",
+    types: ["scatter", "heatmap"],
+  },
+  {
+    title: "Composition",
+    types: ["pie"],
+  },
+  {
+    title: "Progression",
+    types: ["funnel", "waterfall"],
+  },
+];
+
+const CHART_TYPE_MENU_ORDER: ChartType[] = CHART_TYPE_MENU_SECTIONS.flatMap((section) => section.types);
+const HIDDEN_BAR_VARIANT_TYPE_LIST: ChartType[] = [
+  "horizontalBar",
+  "stackedBar",
+  "stackedBar100",
+  "horizontalStackedBar",
+  "horizontalStackedBar100",
+];
+const HIDDEN_BAR_VARIANT_TYPES = new Set<ChartType>(HIDDEN_BAR_VARIANT_TYPE_LIST);
+const BAR_SHAPE_TYPES: ChartType[] = ["bar", "leaderboard"];
+const FUNNEL_SHAPE_TYPES: ChartType[] = ["bar", "funnel"];
+const PIE_SHAPE_TYPES: ChartType[] = ["bar", "pie"];
+const WATERFALL_SHAPE_TYPES: ChartType[] = ["bar", "waterfall"];
+const STACKED_SHAPE_TYPES: ChartType[] = ["bar", "heatmap"];
+const TREND_SHAPE_TYPES: ChartType[] = ["line", "area", "stackedArea", "sparkline", "bar"];
+
+export function isChartType(value: unknown): value is ChartType {
+  return typeof value === "string" && CHART_TYPE_ORDER.includes(value as ChartType);
+}
+
+function chartTypeOptions(types: readonly ChartType[]): ChartTypeOption[] {
+  return types.map((type) => ({
+    label: CHART_TYPE_LABELS[type],
+    type,
+  }));
+}
+
+export function compatibleChartTypesFor(_chart: ChartSpec, _rows: ChartDataRow[]): ChartTypeOption[] {
+  return chartTypeOptions(CHART_TYPE_MENU_ORDER);
+}
+
+function hasMultipleXValues(chart: ChartSpec, rows: ChartDataRow[]): boolean {
+  return new Set(rows.map((row) => String(row[chart.xField] ?? ""))).size >= 2;
+}
+
+function hasNumericX(chart: ChartSpec, rows: ChartDataRow[]): boolean {
+  return rows.some((row) => asNumber(row[chart.xField]) != null);
+}
+
+function hasNumericSeries(chart: ChartSpec, rows: ChartDataRow[], seriesLimit = chart.series.length): boolean {
+  const series = chart.series.slice(0, Math.max(1, seriesLimit));
+  return rows.some((row) => series.some((item) => asNumber(row[item.field]) != null));
+}
+
+function hasPositiveSeries(chart: ChartSpec, rows: ChartDataRow[]): boolean {
+  return rows.some((row) => chart.series.some((item) => (asNumber(row[item.field]) ?? 0) > 0));
+}
+
+function chartTypesForCurrentShape(chart: ChartSpec): ChartType[] {
+  const seriesCount = chart.series.length;
+  if (chart.type === "line" || chart.type === "area" || chart.type === "stackedArea" || chart.type === "sparkline") {
+    return TREND_SHAPE_TYPES;
+  }
+  if (chart.type === "funnel" || chart.intent === "funnel") return FUNNEL_SHAPE_TYPES;
+  if (chart.type === "pie" || chart.intent === "composition") return PIE_SHAPE_TYPES;
+  if (chart.type === "waterfall" || chart.intent === "decomposition") return WATERFALL_SHAPE_TYPES;
+  if (
+    chart.type === "stackedBar" ||
+    chart.type === "stackedBar100" ||
+    chart.type === "horizontalStackedBar" ||
+    chart.type === "horizontalStackedBar100" ||
+    chart.type === "heatmap" ||
+    seriesCount > 1
+  ) {
+    return STACKED_SHAPE_TYPES;
+  }
+  if (chart.type === "bar" || chart.type === "horizontalBar" || chart.type === "leaderboard") {
+    return BAR_SHAPE_TYPES;
+  }
+  if (chart.type === "histogram") return ["histogram"];
+  if (chart.type === "boxPlot") return ["boxPlot"];
+  if (chart.type === "scatter") return ["scatter"];
+  return [chart.type];
+}
+
+function chartTypeCanReuseFields(type: ChartType, chart: ChartSpec, rows: ChartDataRow[]): boolean {
+  if (type === chart.type) return true;
+  if (type === "sparkline" && chart.series.length > 1) return false;
+  if ((type === "line" || type === "area" || type === "stackedArea" || type === "sparkline") && !hasMultipleXValues(chart, rows)) {
+    return false;
+  }
+  if ((type === "funnel" || type === "leaderboard" || type === "waterfall") && chart.series.length > 1) {
+    return false;
+  }
+  if (type === "pie" && !hasPositiveSeries(chart, rows)) return false;
+  if (type === "histogram" && !hasNumericSeries(chart, rows, 1)) return false;
+  if (type === "scatter" && (!hasNumericX(chart, rows) || !hasNumericSeries(chart, rows))) return false;
+  if (type === "heatmap" && chart.series.length < 2) return false;
+  if (type === "boxPlot" && chart.series.length < 5) return false;
+  return true;
+}
+
+function chartTypeAllowedByManifest(type: ChartType, chart: ChartSpec, allowedByManifest: Set<ChartType> | null): boolean {
+  if (!allowedByManifest) return true;
+  if (type === chart.type || allowedByManifest.has(type)) return true;
+  return (
+    type === "bar" &&
+    (HIDDEN_BAR_VARIANT_TYPES.has(chart.type) ||
+      HIDDEN_BAR_VARIANT_TYPE_LIST.some((variant) => allowedByManifest.has(variant)))
+  );
+}
+
+export function compatibleChartTypesForDataShape(chart: ChartSpec, rows: ChartDataRow[]): ChartTypeOption[] {
+  const allowedByManifest = chart.compatibleTypes?.length ? new Set(chart.compatibleTypes) : null;
+  const shapeTypes = chartTypesForCurrentShape(chart).filter((type) => {
+    if (!chartTypeAllowedByManifest(type, chart, allowedByManifest)) return false;
+    return chartTypeCanReuseFields(type, chart, rows);
+  });
+  const orderedTypes = CHART_TYPE_MENU_ORDER.filter((type) => shapeTypes.includes(type));
+  if (!orderedTypes.includes(chart.type) && !HIDDEN_BAR_VARIANT_TYPES.has(chart.type)) orderedTypes.push(chart.type);
+  return chartTypeOptions(orderedTypes);
+}
+
+export function chartTypeSectionsForOptions(options: readonly ChartTypeOption[]): ChartTypeOptionSection[] {
+  const optionByType = new Map(options.map((option) => [option.type, option]));
+  return CHART_TYPE_MENU_SECTIONS.map((section) => ({
+    title: section.title,
+    options: section.types.flatMap((type) => {
+      const option = optionByType.get(type);
+      return option ? [option] : [];
+    }),
+  })).filter((section) => section.options.length > 0);
+}

package/template/.codex/skills/data-analytics/src/analytics-app/charting/chart-contract.ts

@@ -0,0 +1,192 @@
+export const CHART_TYPES = [
+  "line",
+  "area",
+  "stackedArea",
+  "bar",
+  "horizontalBar",
+  "stackedBar",
+  "stackedBar100",
+  "horizontalStackedBar",
+  "horizontalStackedBar100",
+  "histogram",
+  "scatter",
+  "heatmap",
+  "pie",
+  "leaderboard",
+  "sparkline",
+  "funnel",
+  "waterfall",
+  "boxPlot",
+] as const;
+
+export type ChartType = (typeof CHART_TYPES)[number];
+
+export type ValueFormat = "compact" | "number" | "percent" | "currency";
+
+export type ChartSurface = "compact" | "card" | "explorer" | "export";
+
+export type ChartIntent =
+  | "status"
+  | "trend"
+  | "comparison"
+  | "composition"
+  | "decomposition"
+  | "distribution"
+  | "relationship"
+  | "funnel"
+  | "lookup"
+  | "custom";
+
+export type ChartComparisonContext = {
+  baseline?: string;
+  denominator?: string;
+  grain?: string;
+  normalization?: string;
+  semanticFamily?: string;
+  unit?: string;
+};
+
+export type ChartPaletteKind =
+  | "categorical"
+  | "sequential"
+  | "diverging"
+  | "semantic"
+  | "identity";
+
+export type ChartLineStyle = "solid" | "dashed" | "dotted";
+
+export type ChartSeriesColor =
+  | "blue"
+  | "purple"
+  | "green"
+  | "neutral"
+  | "orange"
+  | "yellow"
+  | "pink"
+  | "red";
+
+export type ChartSeriesRole =
+  | "actual"
+  | "baseline"
+  | "target"
+  | "forecast"
+  | "plan"
+  | "comparison";
+
+export type ChartSeriesSpec = {
+  field: string;
+  label?: string;
+  color?: ChartSeriesColor;
+  lineStyle?: ChartLineStyle;
+  role?: ChartSeriesRole;
+  semanticRole?: ChartSeriesRole;
+};
+
+export type ChartEncodingSpec = {
+  field?: string;
+  fields?: string[];
+  type?: "nominal" | "ordinal" | "quantitative" | "temporal" | "text";
+  aggregate?: "none" | "sum" | "avg" | "min" | "max" | "count" | "countDistinct";
+  format?: ValueFormat;
+  label?: string;
+  unit?: string;
+};
+
+export type ChartPaletteSpec = {
+  kind: ChartPaletteKind;
+  name?: string;
+  midpoint?: number;
+};
+
+export type ChartReferenceLineSpec = {
+  axis?: "x" | "y";
+  color?: ChartSeriesColor;
+  label?: string;
+  lineStyle?: ChartLineStyle;
+  value: number | string;
+};
+
+export type ChartLegendOptions = {
+  position?: "bottom" | "right";
+  sort?: "spec" | "labelAsc" | "labelDesc";
+  title?: string;
+};
+
+export type ChartValueLabelMode = "none" | "auto" | "all" | "endpoints";
+
+export type ChartLabelOptions = {
+  values?: ChartValueLabelMode;
+};
+
+export type ChartSurfaceOptions = {
+  surface?: ChartSurface;
+  compact?: boolean;
+  interactiveLegend?: boolean;
+  showControls?: boolean;
+  viewMode?: "visualization" | "table" | "both";
+};
+
+export type ChartBarOrientation = "vertical" | "horizontal";
+
+export type ChartBarGroupMode = "single" | "grouped" | "stacked" | "stacked100";
+
+export type ChartSettings = {
+  bins?: number;
+  categoryLabelPolicy?: "wrap" | "truncate" | "rotate";
+  groupMode?: ChartBarGroupMode;
+  limit?: number;
+  maxSegments?: number;
+  orientation?: ChartBarOrientation;
+  otherThreshold?: number;
+  showLatestValue?: boolean;
+  showPercent?: boolean;
+  showPoints?: "always" | "never";
+  showValues?: boolean;
+  sort?: "none" | "ascending" | "descending" | "custom";
+};
+
+export type ChartSpec = {
+  id: string;
+  title: string;
+  subtitle?: string;
+  showDescription?: boolean;
+  headerMarkdown?: string;
+  intent?: ChartIntent;
+  question?: string;
+  rationale?: string;
+  comparisonContext?: ChartComparisonContext;
+  type: ChartType;
+  dataset: string;
+  sourceId?: string;
+  encodings?: {
+    x?: ChartEncodingSpec;
+    y?: ChartEncodingSpec;
+    color?: ChartEncodingSpec;
+    lineStyle?: ChartEncodingSpec;
+    size?: ChartEncodingSpec;
+    facet?: ChartEncodingSpec;
+    label?: ChartEncodingSpec;
+    tooltip?: ChartEncodingSpec[];
+  };
+  xField?: string;
+  xAxisTitle?: string;
+  yAxisTitle?: string;
+  series?: ChartSeriesSpec[];
+  valueFormat?: ValueFormat;
+  unit?: string;
+  layout?: "full" | "half";
+  combinationRationale?: string;
+  labels?: ChartLabelOptions;
+  legend?: ChartLegendOptions;
+  maxRows?: number;
+  palette?: ChartPaletteSpec;
+  referenceLines?: ChartReferenceLineSpec[];
+  emptyState?: string;
+  compatibleTypes?: ChartType[];
+  settings?: ChartSettings;
+  surface?: ChartSurfaceOptions;
+};
+
+export function isChartType(value: unknown): value is ChartType {
+  return typeof value === "string" && (CHART_TYPES as readonly string[]).includes(value);
+}

package/template/.codex/skills/data-analytics/src/analytics-app/charting/chart-theme.ts

@@ -0,0 +1,203 @@
+import type {
+  ChartBarGroupMode,
+  ChartBarOrientation,
+  ChartLineStyle,
+  ChartPaletteKind,
+  ChartSeriesColor,
+  ChartSeriesRole,
+  ChartType,
+} from "./chart-contract";
+
+export const CHART_TYPE_ORDER: ChartType[] = [
+  "line",
+  "area",
+  "stackedArea",
+  "bar",
+  "horizontalBar",
+  "stackedBar",
+  "stackedBar100",
+  "horizontalStackedBar",
+  "horizontalStackedBar100",
+  "leaderboard",
+  "sparkline",
+  "scatter",
+  "histogram",
+  "heatmap",
+  "pie",
+  "funnel",
+  "waterfall",
+  "boxPlot",
+];
+
+export const CHART_TYPE_LABELS: Record<ChartType, string> = {
+  area: "Area",
+  bar: "Bar",
+  boxPlot: "Box plot",
+  funnel: "Funnel",
+  heatmap: "Heatmap",
+  histogram: "Histogram",
+  horizontalBar: "Horizontal bar",
+  horizontalStackedBar: "Horizontal stacked bar",
+  horizontalStackedBar100: "100% horizontal stacked bar",
+  leaderboard: "Leaderboard",
+  line: "Line",
+  pie: "Pie",
+  scatter: "Scatter",
+  sparkline: "Sparkline",
+  stackedArea: "Stacked area",
+  stackedBar: "Stacked bar",
+  stackedBar100: "100% stacked bar",
+  waterfall: "Waterfall",
+};
+
+export const SERIES_COLORS: Record<ChartSeriesColor, string> = {
+  blue: "var(--ds-chart-series-blue)",
+  purple: "var(--ds-chart-series-purple)",
+  yellow: "var(--ds-chart-series-yellow)",
+  orange: "var(--ds-chart-series-orange)",
+  green: "var(--ds-chart-series-green)",
+  pink: "var(--ds-chart-series-pink)",
+  neutral: "var(--ds-chart-series-neutral)",
+  red: "var(--ds-chart-series-red)",
+};
+
+export const DEFAULT_SERIES_COLOR_ORDER: ChartSeriesColor[] = [
+  "blue",
+  "orange",
+  "green",
+  "purple",
+  "red",
+  "pink",
+  "yellow",
+  "neutral",
+];
+
+export const SEMANTIC_ROLE_COLORS: Partial<Record<ChartSeriesRole, ChartSeriesColor>> = {
+  actual: "blue",
+  baseline: "neutral",
+  comparison: "purple",
+  forecast: "neutral",
+  plan: "neutral",
+  target: "neutral",
+};
+
+export const STACKED_SERIES_FALLBACK_COLORS = [
+  "var(--ds-chart-stack-1)",
+  "var(--ds-chart-stack-2)",
+  "var(--ds-chart-stack-3)",
+  "var(--ds-chart-stack-4)",
+  "var(--ds-chart-stack-5)",
+  "var(--ds-chart-stack-6)",
+  "var(--ds-chart-stack-7)",
+  "var(--ds-chart-stack-8)",
+];
+
+export const SEQUENTIAL_SERIES_COLORS = [
+  "var(--ds-chart-sequential-1)",
+  "var(--ds-chart-sequential-2)",
+  "var(--ds-chart-sequential-3)",
+  "var(--ds-chart-sequential-4)",
+  "var(--ds-chart-sequential-5)",
+  "var(--ds-chart-sequential-6)",
+  "var(--ds-chart-sequential-7)",
+  "var(--ds-chart-sequential-8)",
+  "var(--ds-chart-sequential-9)",
+];
+
+export const DIVERGING_SERIES_COLORS = [
+  "var(--ds-chart-diverging-negative-2)",
+  "var(--ds-chart-diverging-negative-1)",
+  "var(--ds-chart-diverging-neutral)",
+  "var(--ds-chart-diverging-positive-1)",
+  "var(--ds-chart-diverging-positive-2)",
+];
+
+export const HEATMAP_BLUE_SCALE = [
+  "var(--ds-chart-heatmap-1)",
+  "var(--ds-chart-heatmap-2)",
+  "var(--ds-chart-heatmap-3)",
+  "var(--ds-chart-heatmap-4)",
+  "var(--ds-chart-heatmap-5)",
+  "var(--ds-chart-heatmap-6)",
+  "var(--ds-chart-heatmap-7)",
+  "var(--ds-chart-heatmap-8)",
+  "var(--ds-chart-heatmap-9)",
+];
+
+export const FUNNEL_STAGE_COLORS = [
+  "var(--ds-chart-funnel-1)",
+  "var(--ds-chart-funnel-2)",
+  "var(--ds-chart-funnel-3)",
+  "var(--ds-chart-funnel-4)",
+  "var(--ds-chart-funnel-5)",
+];
+
+export function strokeDasharrayForLineStyle(lineStyle: ChartLineStyle | undefined): string | undefined {
+  if (lineStyle === "dotted") return "2 4";
+  if (lineStyle === "dashed") return "5 5";
+  return undefined;
+}
+
+export function colorForSequentialValue(value: number | null, min: number, max: number): string {
+  if (value == null || !Number.isFinite(value)) return SEQUENTIAL_SERIES_COLORS[0];
+  const range = max - min;
+  const intensity = range === 0 ? 1 : (value - min) / range;
+  const index = Math.max(
+    0,
+    Math.min(SEQUENTIAL_SERIES_COLORS.length - 1, Math.round(intensity * (SEQUENTIAL_SERIES_COLORS.length - 1))),
+  );
+  return SEQUENTIAL_SERIES_COLORS[index] ?? SEQUENTIAL_SERIES_COLORS[0];
+}
+
+export function colorForDivergingValue(value: number | null, midpoint = 0): string {
+  if (value == null || !Number.isFinite(value)) return DIVERGING_SERIES_COLORS[2];
+  if (value < midpoint) return DIVERGING_SERIES_COLORS[0];
+  if (value > midpoint) return DIVERGING_SERIES_COLORS[4];
+  return DIVERGING_SERIES_COLORS[2];
+}
+
+export function isStackedChartType(type: ChartType, groupMode?: ChartBarGroupMode): boolean {
+  return (
+    type === "stackedArea" ||
+    type === "stackedBar" ||
+    type === "stackedBar100" ||
+    type === "horizontalStackedBar" ||
+    type === "horizontalStackedBar100" ||
+    (type === "bar" && (groupMode === "stacked" || groupMode === "stacked100"))
+  );
+}
+
+export function isNormalizedStackedChartType(type: ChartType, groupMode?: ChartBarGroupMode): boolean {
+  return type === "stackedBar100" || type === "horizontalStackedBar100" || (type === "bar" && groupMode === "stacked100");
+}
+
+export function isHorizontalChartType(type: ChartType, orientation?: ChartBarOrientation): boolean {
+  return type === "horizontalBar" || type === "horizontalStackedBar" || type === "horizontalStackedBar100" || (type === "bar" && orientation === "horizontal");
+}
+
+export function colorForSeries(
+  color: ChartSeriesColor | undefined,
+  index: number,
+  options: {
+    paletteKind?: ChartPaletteKind;
+    semanticRole?: ChartSeriesRole;
+    singleSeriesTrend?: boolean;
+    stacked?: boolean;
+  } = {},
+): string {
+  if (color) return SERIES_COLORS[color] ?? SERIES_COLORS.blue;
+  if (options.paletteKind === "semantic" && options.semanticRole) {
+    return SERIES_COLORS[SEMANTIC_ROLE_COLORS[options.semanticRole] ?? "blue"];
+  }
+  if (options.paletteKind === "sequential") {
+    return SEQUENTIAL_SERIES_COLORS[index % SEQUENTIAL_SERIES_COLORS.length];
+  }
+  if (options.paletteKind === "diverging") {
+    return DIVERGING_SERIES_COLORS[index % DIVERGING_SERIES_COLORS.length];
+  }
+  if (options.stacked && !color) {
+    return STACKED_SERIES_FALLBACK_COLORS[index % STACKED_SERIES_FALLBACK_COLORS.length];
+  }
+  if (options.singleSeriesTrend && !color) return SERIES_COLORS.blue;
+  return SERIES_COLORS[DEFAULT_SERIES_COLOR_ORDER[index % DEFAULT_SERIES_COLOR_ORDER.length]] ?? SERIES_COLORS.blue;
+}