@ggts-sh/spec 0.43.0

package/src/portable-entry.ts

@@ -0,0 +1,37 @@
+/**
+ * Lean portable builder entry (`@ggts-sh/spec/portable`).
+ *
+ * Exports the fluent builder without TypeBox: `.spec()` is an alias of
+ * `.toPortable()` (normalize only). Use this from chart render bundles;
+ * keep `@ggts-sh/spec` + `.spec()` / `validate()` for agent authoring.
+ *
+ * Lifecycle (Hadley lesson 13; meanings in CONTRIBUTING.md): tags collected
+ * into lifecycle.json by scripts/gen-lifecycle.ts.
+ */
+// @lifecycle-default experimental
+
+export type {
+  AuthoringCellValue,
+  AuthoringColumns,
+  AuthoringDataRef,
+  AuthoringRows,
+  DataInput,
+} from "./builder-data.js";
+
+export type {
+  GeomAreaOptions,
+  GeomBarOptions,
+  GeomBoxplotOptions,
+  GeomColOptions,
+  GeomDensityOptions,
+  GeomHistogramOptions,
+  GeomLineOptions,
+  GeomPointOptions,
+  GeomSmoothOptions,
+  GeomTextOptions,
+} from "./builder-options.js";
+
+export { normalize } from "./normalize.js";
+export type { AesInput, SpecInput } from "./normalize.js";
+
+export { aes, gg, GGBuilder } from "./portable-builder.js";

package/src/position-reference-build.ts

@@ -0,0 +1,164 @@
+/**
+ * POSITION_REFERENCE builder. Gen-only: `scripts/gen-reference-catalogs.ts`.
+ * Runtime uses generated/position-reference-data.ts.
+ */
+import {
+  GEOM_DEFAULTS,
+  KNOWN_GEOMS,
+  KNOWN_POSITIONS,
+  type GeomName,
+  type PositionName,
+} from "./schema-catalog.js";
+import { SpecDeclarations } from "./schema-declarations.js";
+import { buildGeomReference } from "./geom-reference-build.js";
+
+const GEOM_REFERENCE = buildGeomReference();
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface PositionParamDoc {
+  readonly name: string;
+  readonly description: string;
+  readonly typeSummary: string;
+  readonly required: boolean;
+}
+
+export interface PositionReferenceEntry {
+  readonly name: PositionName;
+  /** Route slug — same as position name. */
+  readonly slug: string;
+  /** Short purpose text for the adjustment. */
+  readonly summary: string;
+  /**
+   * Keys of positionParams that apply to this position (from PositionParams
+   * schema, filtered by which adjustment uses them).
+   */
+  readonly params: readonly PositionParamDoc[];
+  /** Geoms whose layer schema allows this position. */
+  readonly compatibleGeoms: readonly GeomName[];
+  /** Geoms whose GEOM_DEFAULTS.position is this position. */
+  readonly defaultForGeoms: readonly GeomName[];
+}
+
+// ---------------------------------------------------------------------------
+// Summaries
+// ---------------------------------------------------------------------------
+
+const POSITION_SUMMARIES: Readonly<Record<PositionName, string>> = Object.freeze({
+  identity:
+    "Leave mark coordinates unchanged. Default for most geoms: each mark keeps its post-stat (x, y).",
+  stack:
+    "Stack groups at each x slot so heights accumulate (positive up, negative down). Default for bar, col, histogram, and area; trains the scale on stacked totals.",
+  fill: "Stack groups then rescale each x slot to proportions (positive and negative runs separately). Same geom set as stack; y domain becomes proportions.",
+  dodge:
+    "Place groups side by side within each x band instead of overlapping. Default for boxplot and violin; used when comparing categories at the same x.",
+  jitter:
+    "Add seeded random offsets so overplotted points separate. Configure with positionParams width/height/seed (always seeded for reproducibility).",
+  nudge:
+    "Apply a fixed offset (positionParams.x / y) per mark — useful for labels beside points. Offsets are data units or band-step fractions.",
+});
+
+/** PositionParams property keys that apply to each position. */
+const PARAM_KEYS_FOR_POSITION: Readonly<Record<PositionName, readonly string[]>> = Object.freeze({
+  identity: [],
+  stack: [],
+  fill: [],
+  dodge: [],
+  jitter: ["width", "height", "seed"],
+  nudge: ["x", "y"],
+});
+
+// ---------------------------------------------------------------------------
+// Schema walkers (minimal; PositionParams is a flat object)
+// ---------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function descriptionOf(node: unknown): string {
+  if (!isRecord(node)) return "";
+  const d = node["description"];
+  return typeof d === "string" ? d : "";
+}
+
+function typeSummaryOf(node: unknown): string {
+  if (!isRecord(node)) return "unknown";
+  const type = node["type"];
+  if (type === "number" || type === "integer") return type === "integer" ? "integer" : "number";
+  if (type === "string") return "string";
+  if (type === "boolean") return "boolean";
+  return "unknown";
+}
+
+function positionParamsDocs(keys: readonly string[]): readonly PositionParamDoc[] {
+  if (keys.length === 0) return Object.freeze([]);
+  const schema = SpecDeclarations.PositionParams as unknown as {
+    properties?: Record<string, unknown>;
+    required?: readonly string[];
+  };
+  const props = schema.properties;
+  if (props === undefined) {
+    throw new Error("POSITION_REFERENCE: PositionParams has no properties");
+  }
+  const required = new Set(schema.required ?? []);
+  const docs: PositionParamDoc[] = [];
+  for (const name of keys) {
+    const propSchema = props[name];
+    if (propSchema === undefined) {
+      throw new Error(`POSITION_REFERENCE: PositionParams missing property "${name}"`);
+    }
+    docs.push({
+      name,
+      description: descriptionOf(propSchema),
+      typeSummary: typeSummaryOf(propSchema),
+      required: required.has(name),
+    });
+  }
+  return Object.freeze(docs);
+}
+
+// ---------------------------------------------------------------------------
+// Build
+// ---------------------------------------------------------------------------
+
+function buildCompatibleGeoms(position: PositionName): readonly GeomName[] {
+  const geoms: GeomName[] = [];
+  for (const geom of KNOWN_GEOMS) {
+    if (GEOM_REFERENCE[geom].allowedPositions.includes(position)) {
+      geoms.push(geom);
+    }
+  }
+  return Object.freeze(geoms);
+}
+
+function buildDefaultForGeoms(position: PositionName): readonly GeomName[] {
+  const geoms: GeomName[] = [];
+  for (const geom of KNOWN_GEOMS) {
+    if (GEOM_DEFAULTS[geom].position === position) {
+      geoms.push(geom);
+    }
+  }
+  return Object.freeze(geoms);
+}
+
+function buildEntry(position: PositionName): PositionReferenceEntry {
+  return Object.freeze({
+    name: position,
+    slug: position,
+    summary: POSITION_SUMMARIES[position],
+    params: positionParamsDocs(PARAM_KEYS_FOR_POSITION[position]),
+    compatibleGeoms: buildCompatibleGeoms(position),
+    defaultForGeoms: buildDefaultForGeoms(position),
+  });
+}
+
+export function buildPositionReference(): Readonly<Record<PositionName, PositionReferenceEntry>> {
+  const out = {} as Record<PositionName, PositionReferenceEntry>;
+  for (const position of KNOWN_POSITIONS) {
+    out[position] = buildEntry(position);
+  }
+  return Object.freeze(out);
+}

package/src/position-reference.ts

@@ -0,0 +1,41 @@
+/**
+ * POSITION_REFERENCE — per-position API docs for the docs site.
+ *
+ * Catalog data is precomputed (`scripts/gen-reference-catalogs.ts`) so
+ * reference pages never load TypeBox. Positions are not Svelte components:
+ * set `position` on a `<Geom*>` shell or JSON layer.
+ */
+import { KNOWN_POSITIONS, type GeomName, type PositionName } from "./schema-catalog.js";
+import { POSITION_REFERENCE_DATA } from "./generated/position-reference-data.js";
+
+export interface PositionParamDoc {
+  readonly name: string;
+  readonly description: string;
+  readonly typeSummary: string;
+  readonly required: boolean;
+}
+
+export interface PositionReferenceEntry {
+  readonly name: PositionName;
+  /** Route slug — same as position name (snake_case). */
+  readonly slug: string;
+  readonly summary: string;
+  /** Params valid for this position (jitter/nudge); empty for others. */
+  readonly params: readonly PositionParamDoc[];
+  /** Geoms whose layer schema allows this position. */
+  readonly compatibleGeoms: readonly GeomName[];
+  /** Geoms whose GEOM_DEFAULTS.position is this position. */
+  readonly defaultForGeoms: readonly GeomName[];
+}
+
+/**
+ * Complete per-position API reference. Keys are exactly KNOWN_POSITIONS.
+ * Precomputed at gen time.
+ */
+export const POSITION_REFERENCE: Readonly<Record<PositionName, PositionReferenceEntry>> =
+  POSITION_REFERENCE_DATA;
+
+/** Stable list order matching KNOWN_POSITIONS (docs index, search, inventory). */
+export function positionReferenceList(): readonly PositionReferenceEntry[] {
+  return KNOWN_POSITIONS.map((position) => POSITION_REFERENCE[position]);
+}

package/src/runtime.ts

@@ -0,0 +1,198 @@
+/**
+ * RuntimeSpec — the in-memory superset of PortableSpec (plan: "Two spec
+ * types, explicitly split"). It adds `{ fn }` channel accessors, which cannot
+ * travel as JSON. Every PortableSpec is a valid RuntimeSpec.
+ *
+ * Narrow with `isPortable()`; convert with `toPortable()` (rejecting) or
+ * `toPortableLossy()` (explicit tooling path) from `portability.ts`.
+ *
+ * The runtime types are projected from their portable counterparts rather
+ * than duplicating the public surface. New portable plot or layer fields are
+ * therefore inherited automatically; only `aes` is widened for accessors.
+ *
+ * The pipeline still consumes PortableSpec. `{ fn }` accessor execution is
+ * future work: this module defines the in-memory type and conversion boundary,
+ * not an execution promise.
+ */
+import type {
+  Aes,
+  AreaLayer,
+  BarLayer,
+  BoxplotLayer,
+  ChannelValue,
+  ColLayer,
+  DensityLayer,
+  ErrorbarLayer,
+  LinerangeLayer,
+  PointrangeLayer,
+  CrossbarLayer,
+  HistogramLayer,
+  FreqpolyLayer,
+  HlineLayer,
+  JitterLayer,
+  LayerSpec,
+  LineLayer,
+  MapLayer,
+  BlankLayer,
+  SfLayer,
+  SfTextLayer,
+  SfLabelLayer,
+  SpokeLayer,
+  PathLayer,
+  PointLayer,
+  PortableSpec,
+  RasterLayer,
+  HexLayer,
+  RectLayer,
+  RibbonLayer,
+  SegmentLayer,
+  CountLayer,
+  ViolinLayer,
+  FunctionLayer,
+  PolygonLayer,
+  AblineLayer,
+  ContourLayer,
+  CurveLayer,
+  Density2dLayer,
+  Density2dFilledLayer,
+  DotplotLayer,
+  RugLayer,
+  StepLayer,
+  QqLayer,
+  QqLineLayer,
+  RuleLayer,
+  QuantileLayer,
+  SmoothLayer,
+  TextLayer,
+  LabelLayer,
+  TileLayer,
+  Bin2dLayer,
+  VlineLayer,
+} from "./schema.js";
+
+/** A function channel accessor: computes the channel value per row. */
+export interface ChannelFn {
+  fn: (row: Record<string, unknown>, index: number) => unknown;
+}
+
+/** A channel value that may also be a function accessor (runtime only). */
+export type RuntimeChannelValue = ChannelValue | ChannelFn;
+
+/** Aes whose channels may be function accessors. */
+type RuntimeAesFields = {
+  [Channel in keyof Aes]: Exclude<Aes[Channel], undefined> | ChannelFn;
+};
+export interface RuntimeAes extends RuntimeAesFields {}
+
+type WithRuntimeAes<Layer extends LayerSpec> = Omit<Layer, "aes"> & {
+  aes?: RuntimeAes;
+};
+
+export interface RuntimePointLayer extends WithRuntimeAes<PointLayer> {}
+export interface RuntimeLineLayer extends WithRuntimeAes<LineLayer> {}
+export interface RuntimePathLayer extends WithRuntimeAes<PathLayer> {}
+export interface RuntimeColLayer extends WithRuntimeAes<ColLayer> {}
+export interface RuntimeBarLayer extends WithRuntimeAes<BarLayer> {}
+export interface RuntimeHistogramLayer extends WithRuntimeAes<HistogramLayer> {}
+export interface RuntimeFreqpolyLayer extends WithRuntimeAes<FreqpolyLayer> {}
+export interface RuntimeAreaLayer extends WithRuntimeAes<AreaLayer> {}
+export interface RuntimeRibbonLayer extends WithRuntimeAes<RibbonLayer> {}
+export interface RuntimeSegmentLayer extends WithRuntimeAes<SegmentLayer> {}
+export interface RuntimeCountLayer extends WithRuntimeAes<CountLayer> {}
+export interface RuntimeViolinLayer extends WithRuntimeAes<ViolinLayer> {}
+export interface RuntimeFunctionLayer extends WithRuntimeAes<FunctionLayer> {}
+export interface RuntimePolygonLayer extends WithRuntimeAes<PolygonLayer> {}
+export interface RuntimeAblineLayer extends WithRuntimeAes<AblineLayer> {}
+export interface RuntimeCurveLayer extends WithRuntimeAes<CurveLayer> {}
+export interface RuntimeRugLayer extends WithRuntimeAes<RugLayer> {}
+export interface RuntimeStepLayer extends WithRuntimeAes<StepLayer> {}
+export interface RuntimeQqLayer extends WithRuntimeAes<QqLayer> {}
+export interface RuntimeQqLineLayer extends WithRuntimeAes<QqLineLayer> {}
+export interface RuntimeRuleLayer extends WithRuntimeAes<RuleLayer> {}
+export interface RuntimeHlineLayer extends WithRuntimeAes<HlineLayer> {}
+export interface RuntimeVlineLayer extends WithRuntimeAes<VlineLayer> {}
+export interface RuntimeJitterLayer extends WithRuntimeAes<JitterLayer> {}
+export interface RuntimeTextLayer extends WithRuntimeAes<TextLayer> {}
+export interface RuntimeLabelLayer extends WithRuntimeAes<LabelLayer> {}
+export interface RuntimeSmoothLayer extends WithRuntimeAes<SmoothLayer> {}
+export interface RuntimeQuantileLayer extends WithRuntimeAes<QuantileLayer> {}
+export interface RuntimeBoxplotLayer extends WithRuntimeAes<BoxplotLayer> {}
+export interface RuntimeDensityLayer extends WithRuntimeAes<DensityLayer> {}
+export interface RuntimeErrorbarLayer extends WithRuntimeAes<ErrorbarLayer> {}
+export interface RuntimeLinerangeLayer extends WithRuntimeAes<LinerangeLayer> {}
+export interface RuntimePointrangeLayer extends WithRuntimeAes<PointrangeLayer> {}
+export interface RuntimeCrossbarLayer extends WithRuntimeAes<CrossbarLayer> {}
+export interface RuntimeRectLayer extends WithRuntimeAes<RectLayer> {}
+export interface RuntimeTileLayer extends WithRuntimeAes<TileLayer> {}
+export interface RuntimeBin2dLayer extends WithRuntimeAes<Bin2dLayer> {}
+export interface RuntimeRasterLayer extends WithRuntimeAes<RasterLayer> {}
+export interface RuntimeHexLayer extends WithRuntimeAes<HexLayer> {}
+export interface RuntimeContourLayer extends WithRuntimeAes<ContourLayer> {}
+export interface RuntimeDensity2dLayer extends WithRuntimeAes<Density2dLayer> {}
+export interface RuntimeDensity2dFilledLayer extends WithRuntimeAes<Density2dFilledLayer> {}
+export interface RuntimeDotplotLayer extends WithRuntimeAes<DotplotLayer> {}
+export interface RuntimeMapLayer extends WithRuntimeAes<MapLayer> {}
+export interface RuntimeBlankLayer extends WithRuntimeAes<BlankLayer> {}
+export interface RuntimeSfLayer extends WithRuntimeAes<SfLayer> {}
+export interface RuntimeSfTextLayer extends WithRuntimeAes<SfTextLayer> {}
+export interface RuntimeSfLabelLayer extends WithRuntimeAes<SfLabelLayer> {}
+
+export interface RuntimeSpokeLayer extends WithRuntimeAes<SpokeLayer> {}
+
+export type RuntimeLayerSpec =
+  | RuntimePointLayer
+  | RuntimeLineLayer
+  | RuntimePathLayer
+  | RuntimeColLayer
+  | RuntimeBarLayer
+  | RuntimeHistogramLayer
+  | RuntimeFreqpolyLayer
+  | RuntimeAreaLayer
+  | RuntimeRibbonLayer
+  | RuntimeSegmentLayer
+  | RuntimeCountLayer
+  | RuntimeViolinLayer
+  | RuntimeFunctionLayer
+  | RuntimePolygonLayer
+  | RuntimeAblineLayer
+  | RuntimeCurveLayer
+  | RuntimeRugLayer
+  | RuntimeStepLayer
+  | RuntimeQqLayer
+  | RuntimeQqLineLayer
+  | RuntimeRuleLayer
+  | RuntimeHlineLayer
+  | RuntimeVlineLayer
+  | RuntimeJitterLayer
+  | RuntimeTextLayer
+  | RuntimeLabelLayer
+  | RuntimeSmoothLayer
+  | RuntimeQuantileLayer
+  | RuntimeBoxplotLayer
+  | RuntimeDensityLayer
+  | RuntimeErrorbarLayer
+  | RuntimeLinerangeLayer
+  | RuntimePointrangeLayer
+  | RuntimeCrossbarLayer
+  | RuntimeRectLayer
+  | RuntimeTileLayer
+  | RuntimeBin2dLayer
+  | RuntimeRasterLayer
+  | RuntimeHexLayer
+  | RuntimeContourLayer
+  | RuntimeDensity2dLayer
+  | RuntimeDensity2dFilledLayer
+  | RuntimeDotplotLayer
+  | RuntimeMapLayer
+  | RuntimeSfLayer
+  | RuntimeSfTextLayer
+  | RuntimeSfLabelLayer
+  | RuntimeBlankLayer
+  | RuntimeSpokeLayer;
+
+/** The in-memory spec superset ({ fn } channel accessors allowed). */
+type RuntimeSpecPortableFields = Omit<PortableSpec, "aes" | "layers">;
+export interface RuntimeSpec extends RuntimeSpecPortableFields {
+  aes?: RuntimeAes;
+  layers: RuntimeLayerSpec[];
+}