@malloydata/render 0.0.419 → 0.0.421

package/dist/module/api/types.d.ts

@@ -1,6 +1,81 @@
 import { DashboardConfig, DrillData, MalloyClickEventPayload, TableConfig, VegaConfigHandler } from '../component/types';
 import { RenderPluginFactory } from './plugin-types';
 export type { RenderFieldMetadata } from '../render-field-metadata';
+/**
+ * Explicit theme overrides applied by the embedder.
+ *
+ * @experimental Provisional surface, not the finished theming feature.
+ * The property set here is deliberately narrow (mostly table and font
+ * chrome) and will be superseded by a designed theme that also covers the
+ * categorical chart palette, typography by role, and continuous color
+ * schemes. Expect this interface to change; pin a renderer version if you
+ * depend on its current shape.
+ *
+ * Resolution order (highest wins): explicit theme key here, then
+ * `# theme.<key>` on the result, then `## theme.<key>` on the model,
+ * then the CSS fallback `var(--malloy-theme--<kebab>)`. Every key is
+ * optional; omitted keys fall through the chain. An empty string is
+ * treated the same as `undefined` so a cleared input drops back to
+ * the next layer.
+ *
+ * This full resolution chain applies to the CSS-variable chrome keys
+ * (the table and font keys, plus `background`), which are emitted as
+ * `--malloy-render--*` variables and must be valid CSS values (e.g.
+ * `"#ff0000"`, `"1px solid #ccc"`, `"14px"`). The `mapColor` key and
+ * the map canvas `background` are consumed inside the Vega spec rather
+ * than via CSS and are read only from this embedder prop; `# theme`
+ * and `## theme` annotations and the CSS fallback do not reach the map
+ * canvas. See the `mapColor` field doc.
+ *
+ * Note: this theme is only read by the modern `MalloyRenderer` /
+ * `MalloyViz` API. The legacy `HTMLView` / `JSONView` exports do not
+ * consult it.
+ *
+ * Note: because the embedder layer is the highest precedence, a model
+ * publisher cannot override an embedder-supplied value with a
+ * `# theme.*` annotation. If you need the model to win for a specific
+ * key, omit that key from the embedder theme.
+ */
+export interface MalloyExplicitTheme {
+    tableRowHeight?: string;
+    tableBodyColor?: string;
+    tableFontSize?: string;
+    tableHeaderColor?: string;
+    tableHeaderWeight?: string;
+    tableBodyWeight?: string;
+    tableBorder?: string;
+    tableBackground?: string;
+    tableGutterSize?: string;
+    tablePinnedBackground?: string;
+    tablePinnedBorder?: string;
+    fontFamily?: string;
+    background?: string;
+    /**
+     * @experimental Provisional, and the last bespoke color knob of this
+     * kind. `mapColor` is the one property that crosses from chrome into
+     * chart-data color; it is kept as a one-off to unblock current embedders.
+     * Further color or theme surface will arrive through the designed theme,
+     * not as additional standalone properties like this one.
+     *
+     * Saturated end of the gradient used by sequential color scales on
+     * `# shape_map` and `# segment_map` choropleth visualizations.
+     *
+     * Unlike the other keys on this interface, `mapColor` is consumed
+     * programmatically by `getColorScale` and baked into the Vega scale
+     * range at render time. It is NOT emitted as a `--malloy-render--*`
+     * CSS variable, so `var()` references won't resolve. Pass a literal
+     * colour string (e.g. `"#ff0000"`).
+     *
+     * The renderer derives the low end of the gradient automatically
+     * (light neutral for dark/medium high-ends, dark neutral for light
+     * high-ends) so the operator only has to pick the brand-saturated
+     * colour. When unset, the renderer uses its built-in blue gradient.
+     *
+     * Rect-mark heatmaps and the legacy `HTMLView` chart paths keep
+     * their existing palettes and ignore this key.
+     */
+    mapColor?: string;
+}
 export interface MalloyRendererOptions {
     onClick?: (payload: MalloyClickEventPayload) => void;
     onDrill?: (drillData: DrillData) => void;
@@ -13,4 +88,14 @@ export interface MalloyRendererOptions {
     plugins?: RenderPluginFactory[];
     pluginOptions?: Record<string, unknown>;
     useVegaInterpreter?: boolean;
+    /**
+     * Optional explicit theme overrides. Keys here take precedence over
+     * any `# theme.*` annotations on the result and over the renderer's
+     * own CSS variable defaults. See {@link MalloyExplicitTheme}.
+     *
+     * @experimental Provisional surface, the shape may change. This is not
+     * yet the finished theming feature; see {@link MalloyExplicitTheme} for
+     * the current property set and that caveat.
+     */
+    theme?: MalloyExplicitTheme;
 }

package/dist/module/component/render-link.d.ts

@@ -1,2 +1,2 @@
 import { Cell, Field } from '../data_tree';
-export declare function renderLink(f: Field, data: Cell): "∅" | import("solid-js").JSX.Element;
+export declare function renderLink(f: Field, data: Cell): import("solid-js").JSX.Element | "∅";

package/dist/module/component/render-list.d.ts

@@ -1,2 +1,2 @@
 import { RendererProps } from './types';
-export declare function renderList(props: RendererProps): "∅" | import("solid-js").JSX.Element;
+export declare function renderList(props: RendererProps): import("solid-js").JSX.Element | "∅";

package/dist/module/component/render-result-metadata.d.ts

@@ -4,6 +4,7 @@ import { ResultStore } from './result-store/result-store';
 import { Runtime } from 'vega';
 import { RootField } from '../data_tree';
 import { RenderFieldMetadata } from '../render-field-metadata';
+import { MalloyExplicitTheme } from '../api/types';
 export type GetResultMetadataOptions = {
     renderFieldMetadata: RenderFieldMetadata;
     getVegaConfigOverride?: VegaConfigHandler;
@@ -12,6 +13,14 @@ export type GetResultMetadataOptions = {
         height: number;
     };
     useVegaInterpreter?: boolean;
+    /**
+     * Operator-level theme passed by the embedding app (e.g. Publisher).
+     * The `# shape_map` and `# segment_map` plugins build their own
+     * colour scales and forward this to {@link getColorScale} so the
+     * gradient picks up the operator's `mapColor` instead of the
+     * hardcoded blue ramp.
+     */
+    explicitTheme?: MalloyExplicitTheme;
 };
 export interface FieldVegaInfo {
     runtime: Runtime | null;

package/dist/module/component/render.d.ts

@@ -1,5 +1,6 @@
 import { Accessor } from 'solid-js';
 import { DashboardConfig, DrillData, MalloyClickEventPayload, TableConfig, VegaConfigHandler } from './types';
+import { MalloyExplicitTheme } from '../api/types';
 import { RenderFieldMetadata } from '../render-field-metadata';
 export type { DrillData } from './types';
 import type * as Malloy from '@malloydata/malloy-interfaces';
@@ -16,6 +17,7 @@ export type MalloyRenderProps = {
     dashboardConfig?: Partial<DashboardConfig>;
     renderFieldMetadata: RenderFieldMetadata;
     useVegaInterpreter?: boolean;
+    theme?: MalloyExplicitTheme;
     onReady?: () => void;
 };
 export declare const useConfig: () => {
@@ -35,4 +37,5 @@ export declare function MalloyRenderInner(props: {
     vegaConfigOverride?: VegaConfigHandler;
     renderFieldMetadata: RenderFieldMetadata;
     useVegaInterpreter?: boolean;
+    theme?: MalloyExplicitTheme;
 }): import("solid-js").JSX.Element;

package/dist/module/component/theme.d.ts

@@ -0,0 +1,6 @@
+import { Tag } from '@malloydata/malloy-tag';
+import { MalloyExplicitTheme } from '../api/types';
+export declare function themeOverridesAsCssVarNames(theme: MalloyExplicitTheme | undefined): Set<string>;
+export declare function getThemeValue(prop: keyof MalloyExplicitTheme, explicitTheme: MalloyExplicitTheme | undefined, ...themes: Array<Tag | undefined>): string;
+export declare function generateThemeStyle(modelTheme?: Tag, localTheme?: Tag, explicitTheme?: MalloyExplicitTheme): string;
+export declare function mergeThemeOption(prev: MalloyExplicitTheme | undefined, hasThemeKey: boolean, next: MalloyExplicitTheme | undefined): MalloyExplicitTheme | undefined;

package/dist/module/data_tree/cells/atomic.d.ts

@@ -48,7 +48,7 @@ export declare class NumberCell extends CellBase {
      * Only valid when stringValue is defined and subtype is 'bigint'.
      */
     bigint(): bigint;
-    compareTo(other: Cell): 1 | 0 | -1;
+    compareTo(other: Cell): 0 | 1 | -1;
     get literalValue(): Malloy.LiteralValue | undefined;
 }
 export declare class DateCell extends CellBase {
@@ -58,7 +58,7 @@ export declare class DateCell extends CellBase {
     constructor(cell: Malloy.CellWithDateCell, field: DateField, parent: NestCell | undefined);
     get value(): Date;
     get timeframe(): Malloy.DateTimeframe | undefined;
-    compareTo(other: Cell): 1 | 0 | -1;
+    compareTo(other: Cell): 0 | 1 | -1;
     get literalValue(): Malloy.LiteralValue | undefined;
 }
 export declare class TimestampCell extends CellBase {
@@ -68,7 +68,7 @@ export declare class TimestampCell extends CellBase {
     constructor(cell: Malloy.CellWithTimestampCell, field: TimestampField, parent: NestCell | undefined);
     get value(): Date;
     get timeframe(): Malloy.TimestampTimeframe | undefined;
-    compareTo(other: Cell): 1 | 0 | -1;
+    compareTo(other: Cell): 0 | 1 | -1;
     get literalValue(): Malloy.LiteralValue | undefined;
 }
 export declare class JSONCell extends CellBase {
@@ -77,7 +77,7 @@ export declare class JSONCell extends CellBase {
     readonly parent: NestCell | undefined;
     constructor(cell: Malloy.CellWithJSONCell, field: JSONField, parent: NestCell | undefined);
     get value(): any;
-    compareTo(other: Cell): 1 | 0 | -1;
+    compareTo(other: Cell): 0 | 1 | -1;
 }
 export declare class SQLNativeCell extends CellBase {
     readonly cell: Malloy.CellWithSQLNativeCell;
@@ -85,7 +85,7 @@ export declare class SQLNativeCell extends CellBase {
     readonly parent: NestCell | undefined;
     constructor(cell: Malloy.CellWithSQLNativeCell, field: SQLNativeField, parent: NestCell | undefined);
     get value(): any;
-    compareTo(other: Cell): 1 | 0 | -1;
+    compareTo(other: Cell): 0 | 1 | -1;
 }
 export declare class StringCell extends CellBase {
     readonly cell: Malloy.CellWithStringCell;
@@ -102,6 +102,6 @@ export declare class BooleanCell extends CellBase {
     readonly parent: NestCell | undefined;
     constructor(cell: Malloy.CellWithBooleanCell, field: BooleanField, parent: NestCell | undefined);
     get value(): boolean;
-    compareTo(other: Cell): 1 | 0 | -1;
+    compareTo(other: Cell): 0 | 1 | -1;
     get literalValue(): Malloy.LiteralValue | undefined;
 }

package/dist/module/html/utils.d.ts

@@ -1,10 +1,12 @@
 import { RenderDef } from './data_styles';
 import { RendererOptions } from './renderer_types';
+import { MalloyExplicitTheme } from '../api/types';
 import { Field } from '../data_tree';
 import type * as Malloy from '@malloydata/malloy-interfaces';
-export declare function getColorScale(type: 'temporal' | 'ordinal' | 'quantitative' | 'nominal' | undefined, isRectMark: boolean, hasOverlappingText?: boolean): {
+export declare function getColorScale(type: 'temporal' | 'ordinal' | 'quantitative' | 'nominal' | undefined, isRectMark: boolean, hasOverlappingText?: boolean, explicitTheme?: MalloyExplicitTheme): {
     range: string[];
 } | undefined;
+export declare function mapCanvasBackground(explicitTheme?: MalloyExplicitTheme): string;
 export declare function timeToString(time: Date, timeframe: Malloy.DateTimeframe | Malloy.TimestampTimeframe | undefined, timezone?: string): string;
 export declare function normalizeToTimezone(date: Date, timezone: string | undefined): Date;
 export declare function yieldTask(): Promise<void>;

package/dist/module/index.d.ts

@@ -5,7 +5,7 @@ export { MalloyRenderer } from './api/malloy-renderer';
 export type { MalloyViz } from './api/malloy-viz';
 export type { CoreVizPluginInstance, RenderPluginInstance, } from './api/plugin-types';
 export { isCoreVizPluginInstance } from './api/plugin-types';
-export type { MalloyRendererOptions, RenderFieldMetadata } from './api/types';
+export type { MalloyExplicitTheme, MalloyRendererOptions, RenderFieldMetadata, } from './api/types';
 export type * from './api/json-schema-types';
 export type { DrillData, MalloyClickEventPayload, TableConfig, DashboardConfig, VegaConfigHandler, } from './component/types';
 export * from './plugins';