@ggts-sh/spec 0.43.0

package/src/schema-decls-scales.ts

@@ -0,0 +1,432 @@
+/**
+ * `$defs` partial — scale base schemas (DomainValue…ColorScaleSpec).
+ * Composed by schema-declarations.ts via spread; key insertion order is load-bearing.
+ */
+
+import Type from "typebox";
+import { COLOR_SCHEME_NAME_SCHEMAS } from "./schema-name-schemas.js";
+import { MAX_BINNED_BREAKS } from "./schema-names.js";
+import {
+  TemporalIntervalSpecSchema,
+  TemporalLabelSpecSchema,
+  TemporalWeekStartSchema,
+} from "./temporal-interval-schema.js";
+import { TemporalParserSpecSchema } from "./temporal-parse-schema.js";
+
+const forbiddenColorOption = () => Type.Optional(Type.Never());
+
+export const ScaleDecls = {
+  DomainValue: Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()], {
+    description:
+      "One domain entry: a number (linear/log), an ISO 8601 date string (time), or a category value (band/ordinal).",
+  }),
+
+  TemporalParserSpec: TemporalParserSpecSchema,
+
+  ScaleExpansion: Type.Object(
+    {
+      mult: Type.Optional(
+        Type.Union(
+          [
+            Type.Number({ minimum: 0 }),
+            Type.Array(Type.Number({ minimum: 0 }), { minItems: 2, maxItems: 2 }),
+          ],
+          {
+            description:
+              "Multiplicative display padding as a fraction of the (transformed) domain span. A scalar pads both ends; a [lower, upper] tuple pads each end. Non-negative and finite.",
+          },
+        ),
+      ),
+      add: Type.Optional(
+        Type.Union(
+          [
+            Type.Number({ minimum: 0 }),
+            Type.Array(Type.Number({ minimum: 0 }), { minItems: 2, maxItems: 2 }),
+          ],
+          {
+            description:
+              "Additive display padding in (transformed) scale units. A scalar pads both ends; a [lower, upper] tuple pads each end. Non-negative and finite.",
+          },
+        ),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Display-domain expansion. Padding is applied after nice in transformed space and never widens the OOB limits. `{ mult: 0, add: 0 }` disables padding.",
+    },
+  ),
+
+  PositionScaleSpec: Type.Intersect([
+    Type.Object(
+      {
+        type: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("linear"),
+              Type.Literal("log"),
+              Type.Literal("time"),
+              Type.Literal("band"),
+              Type.Literal("binned"),
+            ],
+            {
+              description:
+                'Scale type: "linear" (default for numbers), "time" (temporal fields; ISO strings or Date values), "band" (discrete categories), "binned" (quantitative values assigned to ordered bins). "log" is an accepted authored alias that canonicalizes to { type: "linear", transform: "log10" }. Omit to infer from the field type.',
+            },
+          ),
+        ),
+        transform: Type.Optional(
+          Type.Union([Type.Literal("identity"), Type.Literal("log10"), Type.Literal("sqrt")], {
+            description:
+              'Pre-stat position transform applied after parsing and before grouping-sensitive stats/positions. "identity" (default), "log10" (base-10; source values must be > 0), "sqrt" (source values must be >= 0). Only "identity" is permitted on time scales.',
+          }),
+        ),
+        temporalKind: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("date"),
+              Type.Literal("datetime"),
+              Type.Literal("time"),
+              Type.Literal("monthDay"),
+            ],
+            {
+              description:
+                'Temporal precision intent. "date" uses calendar dates; "datetime" uses instants; "time" is time-of-day (portable numbers are seconds since midnight); "monthDay" collapses the year, so the same calendar day from any year shares one position — values parse with the "md" parser and resolve into a fixed leap reference year, and year, clock, weekday and zone label tokens are rejected. A month-day window cannot cross the year boundary. Supplying this option requests a time scale.',
+            },
+          ),
+        ),
+        parse: Type.Optional(
+          Type.Ref("TemporalParserSpec", {
+            description:
+              "Explicit deterministic parser for temporal source values. Omit for value-driven inference.",
+          }),
+        ),
+        parseFailure: Type.Optional(
+          Type.Union([Type.Literal("error"), Type.Literal("censor")], {
+            description:
+              'Explicit parser failure policy: "error" (default) stops with bounded evidence; "censor" converts invalid values to missing and emits a warning.',
+          }),
+        ),
+        timezone: Type.Optional(
+          Type.String({
+            minLength: 1,
+            maxLength: 128,
+            description:
+              'IANA timezone used for timezone-less temporal input. Default "UTC". Invalid zones fail with an actionable diagnostic.',
+          }),
+        ),
+        disambiguation: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("compatible"),
+              Type.Literal("earlier"),
+              Type.Literal("later"),
+              Type.Literal("reject"),
+            ],
+            {
+              description:
+                'DST gap/fold policy for IANA local times. Default "reject"; choose "earlier", "later", or Temporal-compatible behavior explicitly.',
+            },
+          ),
+        ),
+        dateBreaks: Type.Optional(TemporalIntervalSpecSchema),
+        dateMinorBreaks: Type.Optional(TemporalIntervalSpecSchema),
+        dateLabels: Type.Optional(TemporalLabelSpecSchema),
+        locale: Type.Optional(
+          Type.String({
+            minLength: 1,
+            maxLength: 128,
+            description:
+              'BCP 47 locale for temporal labels. Default "en-US". JSON Schema bounds the portable string shape; runtime validation canonicalizes the tag and verifies Intl support before rendering.',
+          }),
+        ),
+        weekStart: Type.Optional(TemporalWeekStartSchema),
+        domain: Type.Optional(
+          Type.Array(Type.Ref("DomainValue"), {
+            minItems: 1,
+            description:
+              "Explicit domain, PINNING the scale: [min, max] for continuous scales (numbers, or temporal strings for time); the full category list for band scales. Data outside the domain is dropped with a warning.",
+          }),
+        ),
+        nice: Type.Optional(
+          Type.Boolean({
+            description:
+              "Round the inferred domain to tick-friendly bounds. Default true. Ignored when `domain` is set.",
+          }),
+        ),
+        zero: Type.Optional(
+          Type.Boolean({
+            description:
+              "Force the domain to include zero. Bars, columns, and areas force this to true on the measure axis; set false explicitly to override. Ignored when `domain` is set.",
+          }),
+        ),
+        reverse: Type.Optional(
+          Type.Boolean({ description: "Reverse the scale's output direction. Default false." }),
+        ),
+        breaks: Type.Optional(
+          Type.Array(Type.Union([Type.Number(), Type.String()]), {
+            minItems: 1,
+            description:
+              "Explicit tick positions in data units (numbers, or ISO date strings for time scales); for binned scales these are the bin boundaries. Omit for automatic ticks. Binned scales allow at most 65 boundaries (64 bins); non-binned explicit ticks are not capped.",
+          }),
+        ),
+        labels: Type.Optional(
+          Type.String({
+            description:
+              'Tick label format string. Time scales: strftime-style ("%Y-%m", "%b %d", "%H:%M"). Numeric scales: ",d" (grouped integer), ".1f" (fixed decimals), ".0%" (percent), "~s" (SI prefix). Omit for automatic formatting.',
+          }),
+        ),
+        expand: Type.Optional(
+          Type.Ref("ScaleExpansion", {
+            description:
+              "Display-domain padding. Non-temporal continuous/binned axes default to { mult: 0.05, add: 0 }; time axes default to zero. Pinned domains still receive display expansion.",
+          }),
+        ),
+        oob: Type.Optional(
+          Type.Union([Type.Literal("censor"), Type.Literal("squish")], {
+            description:
+              'Out-of-bounds policy for values outside explicit source limits, applied before stats. "censor" (default) drops them to missing; "squish" clamps them to the nearest source limit before transform.',
+          }),
+        ),
+        naValue: Type.Optional(
+          Type.Union([Type.Number(), Type.Null()], {
+            description:
+              "Replacement for missing/censored positional values, resolved after OOB and before transform. A finite number substitutes; null (default) keeps them missing. The replacement is itself checked against the transform/domain rules.",
+          }),
+        ),
+        minorBreaks: Type.Optional(
+          Type.Array(Type.Number(), {
+            minItems: 1,
+            description:
+              "Explicit minor gridline positions in semantic source units. Coincident major/minor values render only the major tick. Time scales use dateMinorBreaks instead.",
+          }),
+        ),
+        guide: Type.Optional(Type.Union([Type.Ref("GuideSpec"), Type.Ref("BandAxisGuideSpec")])),
+      },
+      {
+        additionalProperties: false,
+        description: "Configuration for a positional (x or y) scale.",
+      },
+    ),
+    Type.Union([
+      Type.Object({
+        type: Type.Literal("binned"),
+        breaks: Type.Optional(
+          Type.Array(Type.Union([Type.Number(), Type.String()]), {
+            maxItems: MAX_BINNED_BREAKS + 1,
+          }),
+        ),
+      }),
+      Type.Object({
+        type: Type.Optional(
+          Type.Union([
+            Type.Literal("linear"),
+            Type.Literal("log"),
+            Type.Literal("time"),
+            Type.Literal("band"),
+          ]),
+        ),
+      }),
+    ]),
+  ]),
+
+  ColorScaleSpec: Type.Intersect([
+    Type.Object(
+      {
+        type: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("ordinal"),
+              Type.Literal("sequential"),
+              Type.Literal("binned"),
+              Type.Literal("manual"),
+              Type.Literal("identity"),
+            ],
+            {
+              description:
+                'Color scale family: "ordinal" for categories, "sequential" for a continuous ramp, "binned" for color steps, "manual" for an explicit domain/range mapping, or "identity" for validated source colors.',
+            },
+          ),
+        ),
+        transform: Type.Optional(
+          Type.Union([Type.Literal("identity"), Type.Literal("log10"), Type.Literal("sqrt")], {
+            description:
+              "Pre-training quantitative transform for sequential/binned color values. log10/sqrt require non-temporal values; ordinal, manual, and identity families do not accept a transform.",
+          }),
+        ),
+        temporalKind: Type.Optional(
+          Type.Union([Type.Literal("date"), Type.Literal("datetime")], {
+            description:
+              'Temporal precision intent for sequential/binned colors. "date" uses calendar labels; "datetime" uses instant labels.',
+          }),
+        ),
+        parse: Type.Optional(
+          Type.Ref("TemporalParserSpec", {
+            description:
+              "Explicit deterministic parser for temporal color/fill source values. Omit for value-driven inference.",
+          }),
+        ),
+        parseFailure: Type.Optional(
+          Type.Union([Type.Literal("error"), Type.Literal("censor")], {
+            description:
+              'Explicit temporal parser failure policy: "error" (default) or "censor" with a bounded warning.',
+          }),
+        ),
+        timezone: Type.Optional(
+          Type.String({
+            minLength: 1,
+            maxLength: 128,
+            description: 'IANA timezone for temporal color/fill input. Default "UTC".',
+          }),
+        ),
+        disambiguation: Type.Optional(
+          Type.Union([
+            Type.Literal("compatible"),
+            Type.Literal("earlier"),
+            Type.Literal("later"),
+            Type.Literal("reject"),
+          ]),
+        ),
+        domain: Type.Optional(
+          Type.Array(Type.Ref("DomainValue"), {
+            minItems: 1,
+            description:
+              "Explicit semantic domain. Manual/ordinal scales use ordered values; sequential/binned scales use [min, max].",
+          }),
+        ),
+        domainMode: Type.Optional(
+          Type.Union([Type.Literal("grow"), Type.Literal("data")], {
+            description:
+              'Ordinal domain stability: "grow" (default) preserves assignments across filters; "data" rebuilds from current data.',
+          }),
+        ),
+        breaks: Type.Optional(
+          Type.Array(Type.Union([Type.Number(), Type.String()]), {
+            minItems: 2,
+            description:
+              "Explicit semantic reference ticks for sequential colorbars or ordered boundaries for binned colorsteps.",
+          }),
+        ),
+        range: Type.Optional(
+          Type.Array(Type.String({ pattern: "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }), {
+            minItems: 1,
+            description:
+              "Explicit #rgb/#rrggbb colors. Manual pairs them with domain values; sequential/binned interpolate or sample them.",
+          }),
+        ),
+        scheme: Type.Optional(
+          Type.Union(COLOR_SCHEME_NAME_SCHEMAS, {
+            description:
+              'Named color scheme: categorical "observable10" (default), "ipsum", "flexoki", "colorblind", "hue", and ColorBrewer qualitative (Dark2); or sequential family "viridis" (default), "magma", "plasma", "inferno", "cividis", "turbo", plus ColorBrewer sequential/diverging (Blues, RdYlBu, …). Sequential-family names may also be used with ordinal scales (discrete sampling). When type is omitted, the named scheme selects its ordinal or sequential scale family.',
+          }),
+        ),
+        reverse: Type.Optional(
+          Type.Boolean({ description: "Reverse the output color range. Default false." }),
+        ),
+        oob: Type.Optional(
+          Type.Union([Type.Literal("censor"), Type.Literal("squish"), Type.Literal("wrap")], {
+            description:
+              'Out-of-bounds policy for an explicit continuous domain: "censor" (default), "squish", or "wrap" (periodic; required for cyclic *O schemes). Not valid on binned color scales.',
+          }),
+        ),
+        naValue: Type.Optional(
+          Type.String({
+            pattern: "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+            description: "Color for null/missing values. Default9.",
+          }),
+        ),
+        unknownValue: Type.Optional(
+          Type.String({
+            pattern: "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+            description: "Color for invalid, out-of-domain, or unmapped values. Default9.",
+          }),
+        ),
+        onExhaust: Type.Optional(
+          Type.Union([Type.Literal("cycle"), Type.Literal("error")], {
+            description:
+              'Ordinal palette exhaustion policy: "cycle" (default) with a warning, or "error".',
+          }),
+        ),
+        labels: Type.Optional(
+          Type.String({
+            description:
+              'Guide label format: numeric (".1f", ",d", ".0%") or temporal strftime-style text.',
+          }),
+        ),
+        guide: Type.Optional(Type.Ref("GuideSpec")),
+      },
+      {
+        additionalProperties: false,
+        description: "Configuration for a color or fill scale.",
+      },
+    ),
+    Type.Union([
+      Type.Object({
+        type: Type.Literal("binned"),
+        breaks: Type.Optional(
+          Type.Array(Type.Union([Type.Number(), Type.String()]), {
+            minItems: 2,
+            maxItems: MAX_BINNED_BREAKS + 1,
+          }),
+        ),
+        domainMode: forbiddenColorOption(),
+        onExhaust: forbiddenColorOption(),
+      }),
+      Type.Object({
+        type: Type.Literal("manual"),
+        range: Type.Array(Type.String({ pattern: "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }), {
+          minItems: 1,
+        }),
+        transform: forbiddenColorOption(),
+        temporalKind: forbiddenColorOption(),
+        parse: forbiddenColorOption(),
+        parseFailure: forbiddenColorOption(),
+        timezone: forbiddenColorOption(),
+        disambiguation: forbiddenColorOption(),
+        domainMode: forbiddenColorOption(),
+        breaks: forbiddenColorOption(),
+        scheme: forbiddenColorOption(),
+        reverse: forbiddenColorOption(),
+        oob: forbiddenColorOption(),
+        onExhaust: forbiddenColorOption(),
+        labels: forbiddenColorOption(),
+      }),
+      Type.Object({
+        type: Type.Literal("identity"),
+        transform: forbiddenColorOption(),
+        temporalKind: forbiddenColorOption(),
+        parse: forbiddenColorOption(),
+        parseFailure: forbiddenColorOption(),
+        timezone: forbiddenColorOption(),
+        disambiguation: forbiddenColorOption(),
+        domain: forbiddenColorOption(),
+        domainMode: forbiddenColorOption(),
+        breaks: forbiddenColorOption(),
+        range: forbiddenColorOption(),
+        scheme: forbiddenColorOption(),
+        reverse: forbiddenColorOption(),
+        oob: forbiddenColorOption(),
+        onExhaust: forbiddenColorOption(),
+        labels: forbiddenColorOption(),
+      }),
+      Type.Object({
+        type: Type.Literal("ordinal"),
+        transform: forbiddenColorOption(),
+        temporalKind: forbiddenColorOption(),
+        parse: forbiddenColorOption(),
+        parseFailure: forbiddenColorOption(),
+        timezone: forbiddenColorOption(),
+        disambiguation: forbiddenColorOption(),
+        breaks: forbiddenColorOption(),
+        oob: forbiddenColorOption(),
+        labels: forbiddenColorOption(),
+      }),
+      Type.Object({
+        type: Type.Literal("sequential"),
+        domainMode: forbiddenColorOption(),
+        onExhaust: forbiddenColorOption(),
+      }),
+      Type.Object({ type: forbiddenColorOption() }),
+    ]),
+  ]),
+};

package/src/schema-imports.ts

@@ -0,0 +1,116 @@
+/**
+ * Named-defs module surface (public).
+ * `.Import(key)` returns a Cyclic schema rooted at `key` (`$defs` + `$ref`),
+ * matching the TypeBox 0.x Module.Import JSON shape used by the artifact
+ * emitter and by Value.Check / Value.Errors.
+ *
+ * Type inference uses `Static<>` on `SpecDeclarations` (not Cyclic Import):
+ * Cyclic's Static<> collapses large graphs to `never` under TypeScript 6.
+ * We avoid `Type.Module(SpecDeclarations)` for Static extraction — the Module
+ * surface hits TS7056 on composite .d.ts emit once geom unions grow large.
+ *
+ * Build the `$defs` graph once (rooted at PlotSpec) and re-root by swapping
+ * `$ref` — Type.Cyclic(decls, key) per import would rebuild the full graph
+ * ~20× at module load. The re-root trick is load-bearing as a unit: the root
+ * graph, the re-root helper, `SpecModule`, and every `SpecModule.Import`
+ * constant share one `$defs` bag and stay together here (`schema-types.ts`
+ * is type-level only).
+ */
+import Type, { type TSchema } from "typebox";
+
+import { SpecDeclarations } from "./schema-declarations.js";
+
+const SpecDefsRoot = Type.Cyclic(SpecDeclarations, "PlotSpec");
+
+/** Cyclic schema: shared `$defs` bag + root `$ref` (TypeBox 0.x Import shape). */
+export type SpecImportSchema = {
+  $defs: (typeof SpecDefsRoot)["$defs"];
+  $ref: string;
+} & TSchema;
+
+function reRootSpec(key: keyof typeof SpecDeclarations): SpecImportSchema {
+  // One shared `$defs` graph; only the root `$ref` changes per import.
+  const schema: SpecImportSchema = {
+    $defs: SpecDefsRoot.$defs,
+    $ref: key,
+  };
+  return schema;
+}
+
+export const SpecModule = {
+  // oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- preserves TypeBox 0.x instantiation-expression compatibility
+  Import<Key extends keyof typeof SpecDeclarations>(key: Key): SpecImportSchema {
+    return reRootSpec(key);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Imported (validatable) schemas — Cyclic `$defs`+`$ref` for runtime/artifact
+// ---------------------------------------------------------------------------
+
+export const PlotSpecSchema = SpecModule.Import("PlotSpec");
+export const LayerSpecSchema = SpecModule.Import("LayerSpec");
+export const PointLayerSchema = SpecModule.Import("PointLayer");
+export const LineLayerSchema = SpecModule.Import("LineLayer");
+export const PathLayerSchema = SpecModule.Import("PathLayer");
+export const ColLayerSchema = SpecModule.Import("ColLayer");
+export const BarLayerSchema = SpecModule.Import("BarLayer");
+export const HistogramLayerSchema = SpecModule.Import("HistogramLayer");
+export const FreqpolyLayerSchema = SpecModule.Import("FreqpolyLayer");
+export const AreaLayerSchema = SpecModule.Import("AreaLayer");
+export const RibbonLayerSchema = SpecModule.Import("RibbonLayer");
+export const SegmentLayerSchema = SpecModule.Import("SegmentLayer");
+export const CountLayerSchema = SpecModule.Import("CountLayer");
+export const ViolinLayerSchema = SpecModule.Import("ViolinLayer");
+export const FunctionLayerSchema = SpecModule.Import("FunctionLayer");
+export const PolygonLayerSchema = SpecModule.Import("PolygonLayer");
+export const AblineLayerSchema = SpecModule.Import("AblineLayer");
+export const CurveLayerSchema = SpecModule.Import("CurveLayer");
+export const MapLayerSchema = SpecModule.Import("MapLayer");
+export const BlankLayerSchema = SpecModule.Import("BlankLayer");
+export const SfLayerSchema = SpecModule.Import("SfLayer");
+export const SfTextLayerSchema = SpecModule.Import("SfTextLayer");
+export const SfLabelLayerSchema = SpecModule.Import("SfLabelLayer");
+
+export const SpokeLayerSchema = SpecModule.Import("SpokeLayer");
+export const RugLayerSchema = SpecModule.Import("RugLayer");
+export const StepLayerSchema = SpecModule.Import("StepLayer");
+export const QqLayerSchema = SpecModule.Import("QqLayer");
+export const QqLineLayerSchema = SpecModule.Import("QqLineLayer");
+export const RuleLayerSchema = SpecModule.Import("RuleLayer");
+export const HlineLayerSchema = SpecModule.Import("HlineLayer");
+export const VlineLayerSchema = SpecModule.Import("VlineLayer");
+export const JitterLayerSchema = SpecModule.Import("JitterLayer");
+export const TextLayerSchema = SpecModule.Import("TextLayer");
+export const LabelLayerSchema = SpecModule.Import("LabelLayer");
+export const SmoothLayerSchema = SpecModule.Import("SmoothLayer");
+export const QuantileLayerSchema = SpecModule.Import("QuantileLayer");
+export const ContourLayerSchema = SpecModule.Import("ContourLayer");
+export const BoxplotLayerSchema = SpecModule.Import("BoxplotLayer");
+export const DensityLayerSchema = SpecModule.Import("DensityLayer");
+export const Density2dLayerSchema = SpecModule.Import("Density2dLayer");
+export const Density2dFilledLayerSchema = SpecModule.Import("Density2dFilledLayer");
+export const DotplotLayerSchema = SpecModule.Import("DotplotLayer");
+export const ErrorbarLayerSchema = SpecModule.Import("ErrorbarLayer");
+export const LinerangeLayerSchema = SpecModule.Import("LinerangeLayer");
+export const PointrangeLayerSchema = SpecModule.Import("PointrangeLayer");
+export const CrossbarLayerSchema = SpecModule.Import("CrossbarLayer");
+export const RectLayerSchema = SpecModule.Import("RectLayer");
+export const TileLayerSchema = SpecModule.Import("TileLayer");
+export const Bin2dLayerSchema = SpecModule.Import("Bin2dLayer");
+export const RasterLayerSchema = SpecModule.Import("RasterLayer");
+export const HexLayerSchema = SpecModule.Import("HexLayer");
+export const AesSchema = SpecModule.Import("Aes");
+export const ChannelValueSchema = SpecModule.Import("ChannelValue");
+export const DataRefSchema = SpecModule.Import("DataRef");
+export const ScalesSchema = SpecModule.Import("Scales");
+export const TemporalParserSpecSchemaRef = SpecModule.Import("TemporalParserSpec");
+export const FacetFieldRefSchema = SpecModule.Import("FacetFieldRef");
+export const FacetStripSpecSchema = SpecModule.Import("FacetStripSpec");
+export const FacetSpecSchema = SpecModule.Import("FacetSpec");
+export const CoordTransformAxisSpecSchema = SpecModule.Import("CoordTransformAxisSpec");
+export const CoordTransformSpecSchema = SpecModule.Import("CoordTransformSpec");
+export const CoordFixedSpecSchema = SpecModule.Import("CoordFixedSpec");
+export const CoordSfSpecSchema = SpecModule.Import("CoordSfSpec");
+export const CoordRadialSpecSchema = SpecModule.Import("CoordRadialSpec");
+export const CoordSpecSchema = SpecModule.Import("CoordSpec");

package/src/schema-name-schemas.ts

@@ -0,0 +1,37 @@
+/**
+ * TypeBox literals for closed name registries (schema graph only).
+ * Runtime name arrays live in schema-names.ts without a typebox import.
+ */
+import Type, { type TLiteral } from "typebox";
+
+import {
+  COLOR_SCHEME_NAMES,
+  LINETYPE_NAMES,
+  POINT_SHAPE_NAMES,
+  THEME_NAMES,
+  type LinetypeName,
+  type PointShapeName,
+} from "./schema-names.js";
+
+type ColorSchemeNameValue = (typeof COLOR_SCHEME_NAMES)[number];
+/** TypeBox literals for color scheme names (used by ColorScaleSpec). */
+export const COLOR_SCHEME_NAME_SCHEMAS = COLOR_SCHEME_NAMES.map((name) =>
+  Type.Literal(name),
+) as unknown as [TLiteral<ColorSchemeNameValue>, ...TLiteral<ColorSchemeNameValue>[]];
+
+type PointShapeNameValue = PointShapeName;
+export const POINT_SHAPE_NAME_SCHEMAS = POINT_SHAPE_NAMES.map((name) =>
+  Type.Literal(name),
+) as unknown as [TLiteral<PointShapeNameValue>, ...TLiteral<PointShapeNameValue>[]];
+
+type LinetypeNameValue = LinetypeName;
+export const LINETYPE_NAME_SCHEMAS = LINETYPE_NAMES.map((name) =>
+  Type.Literal(name),
+) as unknown as [TLiteral<LinetypeNameValue>, ...TLiteral<LinetypeNameValue>[]];
+
+type ThemeNameValue = (typeof THEME_NAMES)[number];
+/** TypeBox literals for theme names (used by ThemeName def). */
+export const THEME_NAME_SCHEMAS = THEME_NAMES.map((name) => Type.Literal(name)) as unknown as [
+  TLiteral<ThemeNameValue>,
+  ...TLiteral<ThemeNameValue>[],
+];