@object-ui/core 17.3.0 → 17.6.0

package/dist/theme/ThemeEngine.js

@@ -116,41 +116,33 @@ export function generateColorVars(colors) {
 /**
  * Generate CSS custom properties from a Theme's typography config.
  */
+// ----------------------------------------------------------------------------
+// RETIRED THEME BLOCKS — @objectstack/spec 17.0.0-rc.3 (objectstack#5021 option
+// 2, PR objectstack#5289), objectui#3361.
+//
+// `theme.animation`, `theme.zIndex` and five typography groups
+// (`fontSize` / `fontWeight` / `lineHeight` / `letterSpacing`, plus
+// `fontFamily.heading` / `fontFamily.mono`) became TOMBSTONES: the schema now
+// rejects them by name and their prescription points at `theme.customVars`, the
+// declared — and since #5021 the only — door for a custom property. A
+// `--z-modal` or a `--duration-fast` is authored there now, emitted verbatim as
+// `--<key>: <value>`.
+//
+// The emission code below them was therefore structurally dead: no author can
+// produce the input that would reach it. It is removed rather than left behind
+// a cast, because the tombstoned keys type as `never` and any cast that made
+// them compile would fossilize a shape the contract has withdrawn (AGENTS.md
+// #0.1). LIVE emission — `colors`, `borderRadius`, `shadows`,
+// `typography.fontFamily.base` (→ `--font-sans`) and `customVars` — is
+// untouched, byte for byte.
+// ----------------------------------------------------------------------------
 export function generateTypographyVars(typography) {
     const vars = {};
+    // `fontFamily.base` is the only surviving typography input — see the RETIRED
+    // THEME BLOCKS note above for where the other five groups went.
     if (typography.fontFamily?.base) {
         vars['--font-sans'] = typography.fontFamily.base;
     }
-    if (typography.fontFamily?.heading) {
-        vars['--font-heading'] = typography.fontFamily.heading;
-    }
-    if (typography.fontFamily?.mono) {
-        vars['--font-mono'] = typography.fontFamily.mono;
-    }
-    if (typography.fontSize) {
-        for (const [key, value] of Object.entries(typography.fontSize)) {
-            if (value)
-                vars[`--font-size-${key}`] = value;
-        }
-    }
-    if (typography.fontWeight) {
-        for (const [key, value] of Object.entries(typography.fontWeight)) {
-            if (value != null)
-                vars[`--font-weight-${key}`] = String(value);
-        }
-    }
-    if (typography.lineHeight) {
-        for (const [key, value] of Object.entries(typography.lineHeight)) {
-            if (value)
-                vars[`--line-height-${key}`] = value;
-        }
-    }
-    if (typography.letterSpacing) {
-        for (const [key, value] of Object.entries(typography.letterSpacing)) {
-            if (value)
-                vars[`--letter-spacing-${key}`] = value;
-        }
-    }
     return vars;
 }
 /**
@@ -197,36 +189,6 @@ export function generateShadowVars(shadows) {
     }
     return vars;
 }
-/**
- * Generate CSS custom properties from a Theme's animation config.
- */
-export function generateAnimationVars(animation) {
-    const vars = {};
-    if (animation.duration) {
-        for (const [key, value] of Object.entries(animation.duration)) {
-            if (value)
-                vars[`--duration-${key}`] = value;
-        }
-    }
-    if (animation.timing) {
-        for (const [key, value] of Object.entries(animation.timing)) {
-            if (value)
-                vars[`--timing-${key}`] = value;
-        }
-    }
-    return vars;
-}
-/**
- * Generate CSS custom properties from a Theme's z-index config.
- */
-export function generateZIndexVars(zIndex) {
-    const vars = {};
-    for (const [key, value] of Object.entries(zIndex)) {
-        if (value != null)
-            vars[`--z-${key}`] = String(value);
-    }
-    return vars;
-}
 /**
  * Generate ALL CSS custom properties from a complete Theme.
  * This is the main entry point for theme → CSS conversion.
@@ -247,14 +209,6 @@ export function generateThemeVars(theme) {
     if (theme.shadows) {
         Object.assign(vars, generateShadowVars(theme.shadows));
     }
-    // Animation
-    if (theme.animation) {
-        Object.assign(vars, generateAnimationVars(theme.animation));
-    }
-    // Z-Index
-    if (theme.zIndex) {
-        Object.assign(vars, generateZIndexVars(theme.zIndex));
-    }
     // Custom CSS variables (passthrough)
     if (theme.customVars) {
         for (const [key, value] of Object.entries(theme.customVars)) {
@@ -290,22 +244,6 @@ export function mergeThemes(parent, child) {
                     ...parent.typography?.fontFamily,
                     ...child.typography?.fontFamily,
                 },
-                fontSize: {
-                    ...parent.typography?.fontSize,
-                    ...child.typography?.fontSize,
-                },
-                fontWeight: {
-                    ...parent.typography?.fontWeight,
-                    ...child.typography?.fontWeight,
-                },
-                lineHeight: {
-                    ...parent.typography?.lineHeight,
-                    ...child.typography?.lineHeight,
-                },
-                letterSpacing: {
-                    ...parent.typography?.letterSpacing,
-                    ...child.typography?.letterSpacing,
-                },
             }
             : undefined,
         // Deep-merge border radius
@@ -316,25 +254,6 @@ export function mergeThemes(parent, child) {
         shadows: child.shadows || parent.shadows
             ? { ...parent.shadows, ...child.shadows }
             : undefined,
-        // Deep-merge animation
-        animation: child.animation || parent.animation
-            ? {
-                ...parent.animation,
-                ...child.animation,
-                duration: {
-                    ...parent.animation?.duration,
-                    ...child.animation?.duration,
-                },
-                timing: {
-                    ...parent.animation?.timing,
-                    ...child.animation?.timing,
-                },
-            }
-            : undefined,
-        // Deep-merge zIndex
-        zIndex: child.zIndex || parent.zIndex
-            ? { ...parent.zIndex, ...child.zIndex }
-            : undefined,
         // Deep-merge customVars
         customVars: child.customVars || parent.customVars
             ? { ...parent.customVars, ...child.customVars }

package/dist/theme/index.d.ts

@@ -5,4 +5,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine.js';

package/dist/theme/index.js

@@ -5,4 +5,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, 
+// `generateAnimationVars` / `generateZIndexVars` removed with the
+// `theme.animation` / `theme.zIndex` tombstones in @objectstack/spec
+// 17.0.0-rc.3 (objectstack#5021) — see ThemeEngine's RETIRED THEME BLOCKS
+// note. `theme.customVars` is the declared door for a `--duration-*` or
+// `--z-*` now.
+generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine.js';

package/dist/types/index.d.ts

@@ -5,15 +5,128 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export interface SchemaNode {
-    type: string;
-    id?: string;
-    className?: string;
-    data?: any;
-    body?: SchemaNode | SchemaNode[];
-    [key: string]: any;
-}
-export interface ComponentRendererProps {
-    schema: SchemaNode;
-    [key: string]: any;
-}
+/**
+ * One `SchemaNode` (objectui#4580).
+ *
+ * This package used to hand-declare `interface SchemaNode { type: string; …
+ * [key: string]: any }` here, while `@object-ui/types` exported
+ * `type SchemaNode = BaseSchema | string | number | boolean | null | undefined`
+ * — two different types under one name, from two packages the same consumers
+ * import together. Which declaration a call site got depended on which package
+ * it happened to import from, and #4548's option-A canary measured **19 of 35**
+ * errors as exactly that collision:
+ *
+ * ```
+ * Type 'import(".../packages/types/dist/base").SchemaNode' is not assignable to
+ * type 'import(".../packages/core/dist/types/index").SchemaNode'
+ * ```
+ *
+ * PR #4578 sidestepped it — `SchemaRenderer` states its own component-level
+ * union rather than picking a side — and left the reconciliation to this card.
+ *
+ * **`@object-ui/types`' union wins**, per #4580's ruling 1: it is the spec of
+ * record (its own doc comment names `'Plain string'` a valid node), and it is
+ * the side the measured collisions resolve toward. The declaration is RE-EXPORTED
+ * rather than restated, so there is exactly one declaration left to disagree
+ * with — a structural copy would reproduce the defect the moment either side
+ * moved. This package already depends on `@object-ui/types`, so the edge exists
+ * and adds no cycle.
+ *
+ * ## The entry-surface sentence that used to close this block is WITHDRAWN
+ *
+ * It read: *core's own entry surface is unchanged (`dist/index.d.ts` is
+ * byte-identical across the change — measured, both rounds)*. The reading was
+ * real, and it certified nothing (objectui#5673).
+ *
+ * `core/dist/index.d.ts` is emitted from a barrel that only FORWARDS this
+ * symbol, and forwarding never restates a shape — not `export *`, and not the
+ * `export type { SchemaNode, … } from './types/index.js'` line that names it.
+ * Only the module that DECLARES the symbol can move. So that file is
+ * byte-identical under any change to a re-exported declaration's shape, naming
+ * the symbol or not, and a gauge that cannot fail for the change class it is
+ * quoted against has discharged nothing.
+ *
+ * ## The gauge that can fail — and how to prove it can, before believing it
+ *
+ * 1. Watch the emitted `.d.ts` of the module that DECLARES the symbol. For
+ *    `SchemaNode` that is `@object-ui/types`' `dist/base.d.ts`, in another
+ *    package — not core's entry, and not core's own `dist/types/index.d.ts`
+ *    either, which forwards exactly as the entry does. For the shape claim
+ *    itself, resolve the symbol through the TypeScript CHECKER from
+ *    `core/dist/index.d.ts`.
+ * 2. Build both legs from a cleared `dist/` AND a cleared
+ *    `tsconfig.tsbuildinfo` — the build info lives outside `dist/`, so
+ *    composite `tsc` skips emit if it survives and two stale trees compare
+ *    equal for free.
+ * 3. CALIBRATE: inject a probe key into the declaring module, rebuild, and
+ *    require the hash you are watching to MOVE; drop the probe, rebuild, and
+ *    require it to come back to its original value. A probe that leaves your
+ *    hash unmoved means the gauge is not wired to this symbol — that is what
+ *    failure looks like here, and no "byte-identical" sentence may be written
+ *    from a gauge that just failed it.
+ *
+ * Run against this file's own claim — probe: one additive optional key on
+ * `BaseSchema`, the shape `SchemaNode` publishes — `@object-ui/types`'
+ * `dist/base.d.ts` moved and came back, while `core/dist/index.d.ts` and
+ * `core/dist/types/index.d.ts` held one hash across all three legs. The
+ * withdrawn sentence was watching the two files that cannot move.
+ *
+ * The collision is only observable from a package that resolves BOTH through
+ * `node_modules`; the pin therefore lives in `@object-ui/react`
+ * (`src/__tests__/SchemaNode.reconciliation.test.ts`), not here.
+ */
+export type { SchemaNode } from '@object-ui/types';
+/**
+ * One `ComponentRendererProps` (objectui#4594).
+ *
+ * This package used to hand-declare `interface ComponentRendererProps
+ * { schema: SchemaNode; [key: string]: any }` here — two lines below `SchemaNode`
+ * and against `@object-ui/types`' generic
+ * `ComponentRendererProps< TSchema extends BaseSchema = BaseSchema >`. Same name,
+ * two packages the same consumers import together: the second such pair in this
+ * one file, and the third across this fault line after `SchemaNode` (#4580) and
+ * `ComponentInput` (#4972).
+ *
+ * **`@object-ui/types`' generic declaration wins**, and is RE-EXPORTED rather
+ * than restated, so there is exactly one declaration left to disagree with — a
+ * structural copy would reproduce the defect the moment either side moved.
+ *
+ * Reconciled now, at **zero consumers** — re-verified on the merged ref rather
+ * than inherited from the card: repo-wide, `ComponentRendererProps` occurred only
+ * at the two declarations, each package's own entry re-export, and one line of
+ * `packages/components/CHANGELOG.md` recording that nothing used it. Zero
+ * consumers is why this is cheap today and would not stay cheap: the day someone
+ * imports it, which declaration they get decides whether a primitive node is
+ * admissible.
+ *
+ * ## What the re-export moves, and how that was measured
+ *
+ * It is NOT surface-neutral, and the gauge that would have said so is vacuous.
+ * `core/dist/index.d.ts` is emitted from a barrel that only FORWARDS this
+ * symbol — its `export type { … }` line names it, and naming is not restating
+ * — so that file is byte-identical under ANY change to a re-exported
+ * declaration's shape and cannot fail for this change class (objectui#5673,
+ * where the `SchemaNode` block above withdraws the same reading and carries the
+ * probe calibration that tells a live gauge from this one).
+ *
+ * Measured instead by resolving the symbol through the TypeScript CHECKER from
+ * `core/dist/index.d.ts`, over a `dist/` + `tsconfig.tsbuildinfo` clean rebuild
+ * on both legs (the build info lives outside `dist/`, so composite `tsc` skips
+ * emit if it survives and two stale trees compare equal for free):
+ *
+ * ```
+ * before   ComponentRendererProps            schema: BaseSchema | string | number | boolean | null | undefined
+ * after    ComponentRendererProps<TSchema>   schema: TSchema  (TSchema extends BaseSchema = BaseSchema)
+ * ```
+ *
+ * So `schema` NARROWS back to the object form — core's copy had silently widened
+ * when #4608 made `SchemaNode` a re-export of types' union, which is the interim
+ * state this card closes — and the type gains a parameter. Nothing downstream
+ * can observe either move, because nothing imports it.
+ *
+ * The collision is only observable from a package that resolves BOTH through
+ * `node_modules`; the pin therefore lives in `@object-ui/react`
+ * (`src/__tests__/ComponentRendererProps.reconciliation.test.ts`), not here —
+ * same position, same reason, as `SchemaNode`'s pin above.
+ */
+export type { ComponentRendererProps } from '@object-ui/types';

package/dist/utils/chart-presentation.d.ts

@@ -0,0 +1,205 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * chart-presentation — the AUTHORED half of a dataset-bound chart, lowered onto
+ * the bindings {@link buildChartSeries} derived from the dataset selection.
+ *
+ * `chart-series.ts` beside this file owns the DATA half: which columns become
+ * series, which rows, which buckets. This file owns everything the author gets
+ * to say about how that data LOOKS — the ruled data/presentation split of
+ * objectui#4229, stated once:
+ *
+ *  - **Data (derived, never forwarded)** — series MEMBERSHIP and the column each
+ *    binding reads. Concretely `buildChartSeries`' `dataKey`s, `xAxisKey`, and
+ *    the spec's two binding keys `ChartSeries.name` and `ChartAxis.field`.
+ *  - **Presentation (authored, merged forward)** — everything else on those same
+ *    objects: `series[].type` (the per-series mark), `series[].yAxis` (which
+ *    axis it binds to), `label`/`color`/`stack`/`variant`/`dashArray`/`opacity`,
+ *    the axis definitions' `title`/`format`/`min`/`max`/`stepSize`/
+ *    `showGridLines`/`position`/`logarithmic`, and the chart chrome
+ *    (`showLegend`, `showDataLabels`, `colors`, `annotations`, …).
+ *
+ * ## Why it lives in `@object-ui/core` rather than in one plugin
+ *
+ * It was written for `plugin-dashboard`'s `DatasetWidget` (#3135 → objectstack#7016
+ * → #4229) and lifted here by objectui#4877, when `plugin-report`'s embedded
+ * report chart turned out to need the SAME merge over the same spec shapes: the
+ * report was forwarding six keys and dropping every authored chrome key the
+ * schema declares, and re-deriving this beside the dashboard's copy is exactly
+ * the duplication objectui#4389 filed as a defect (two longhand copies of the
+ * analytics label net, one per plugin, drifting apart).
+ *
+ * Everything here is a pure data transform over plain records, so it sits below
+ * both plugins with no React and no i18n — the same layering `chart-series.ts`
+ * already has (see {@link OptionLabelTranslator} there for why an i18n-resolved
+ * string always arrives as an ARGUMENT rather than being read here).
+ *
+ * ## Two entry points, because the two surfaces declare axes differently
+ *
+ * A dashboard widget's `chartConfig` spells its axes as spec `ChartAxis`
+ * OBJECTS. A report's `chart.xAxis` / `chart.yAxis` are bare dimension/measure
+ * NAME strings — on that surface the axes are pure DATA (they ARE the selection)
+ * and carry no presentation at all. So:
+ *
+ *  - {@link mergeAuthoredPresentation} is the object-axis entry point: series
+ *    merge + axis presentation, for a caller whose axes are `ChartAxis` objects.
+ *  - {@link mergeAuthoredSeries} is the series merge ALONE, for a caller whose
+ *    axes are names. That split is structural, not a guard: handing a bare
+ *    string to {@link mergeAuthoredPresentation} would run it through
+ *    `axisPresentation`, which reads nothing off a string and would synthesise a
+ *    `yAxis: [{}]` entry — a y-axis declaring nothing but its own existence,
+ *    which is precisely how the COUNT of entries turns on a secondary axis. A
+ *    surface that cannot author axis presentation should not be able to reach
+ *    the code that reads it.
+ */
+import type { ChartSeriesBinding } from './chart-series.js';
+/** Authored spec `ChartSeries` presentation, in the renderer's internal spelling. */
+export interface AuthoredSeriesPresentation {
+    label?: string;
+    /** Spec `ChartSeries.type`, narrowed — see {@link seriesPresentation}. */
+    chartType?: 'bar' | 'line' | 'area';
+    yAxis?: 'left' | 'right';
+    color?: string;
+    stack?: string;
+    variant?: 'primary' | 'comparison';
+    dashArray?: string;
+    opacity?: number;
+}
+/** A derived series binding with the author's presentation merged onto it. */
+export type MergedChartSeries = ChartSeriesBinding & AuthoredSeriesPresentation;
+/**
+ * One authored `ChartSeries`, minus its `name` — i.e. everything about it that
+ * is presentation rather than membership.
+ *
+ * `type` is narrowed to the three families that COMPOSE on one cartesian plot,
+ * because this array reaches the renderer already speaking the internal shape
+ * (`ChartRenderer` forwards a `dataKey`-shaped array untouched, so
+ * `normalizeChartSchema`'s own identical narrowing never sees it). Without the
+ * narrowing a `type: 'pie'` would not merely be inert — it would count as a
+ * family disagreement in `effectiveChartFamily`, flip the whole chart into a
+ * combo, and then draw that series as a bar anyway.
+ */
+export declare function seriesPresentation(raw: Record<string, unknown>): AuthoredSeriesPresentation;
+/**
+ * One authored `ChartAxis`, minus its `field` — the axis's presentation.
+ *
+ * `field` is the one DATA key on an axis (it names the plotted column), and
+ * dropping it here is what keeps membership with the dataset **structurally**
+ * rather than by a guard: `normalizeChartSchema` synthesises series out of
+ * `yAxis[].field` when a chart declares no series, so a forwarded `field`
+ * would be a live membership channel on an empty selection. With it gone the
+ * axis carries scale and chrome only, and the count of entries — which is what
+ * turns on the secondary axis (`yAxes.length > 1`) — survives, including for
+ * an entry that declares nothing but its own existence.
+ *
+ * Keys the renderer does not read on a given axis are dropped by
+ * `normalizeChartSchema`, the ONE normalization layer (#2880 S1): today it
+ * keeps `format`/`title`/`showGridLines` on the x-axis and the full set on the
+ * y-axes. That narrowing is deliberately NOT mirrored here — a second copy
+ * would drift from the renderer's real capability the moment it grew.
+ */
+export declare function axisPresentation(raw: unknown): Record<string, unknown>;
+/**
+ * Merge an authored `series[]` array's PRESENTATION onto the bindings the
+ * dataset selection derived — the series half of #4229's split, and the whole
+ * of it for a surface whose axes are names rather than objects (see the file
+ * header).
+ *
+ * The match rule is **by name/key**: an authored `series[].name` is paired with
+ * the derived binding whose `dataKey` it equals, and the pairing decides
+ * nothing but presentation:
+ *
+ *  - an authored entry naming a measure that is NOT in the dataset selection is
+ *    **ignored** — membership belongs to the dataset, so an author cannot add,
+ *    remove or re-point a series from the chart config;
+ *  - a derived series with no authored entry keeps the family default, so every
+ *    surface that never wrote `series` renders byte-for-byte as before;
+ *  - where both exist the **explicit binding wins** (#2880 S2), which is the
+ *    whole point: `type: 'line'` + `yAxis: 'right'` is how the spec says "this
+ *    measure is a line on the secondary axis".
+ *
+ * Matching on `name` only is deliberate: `name` is the spec's authorable key
+ * for a series (`dataKey` is a declared ALIAS of it, resolved where the
+ * metadata is parsed), so reading a second spelling here would fossilize a
+ * dialect this renderer has no business accepting (AGENTS.md #0.1).
+ *
+ * The FIRST entry naming a measure wins; a later duplicate cannot silently
+ * reconfigure a series the author already described.
+ *
+ * @param derived the bindings {@link buildChartSeries} produced from the selection
+ * @param authoredSeries the authored `series` array (anything, incl. absent)
+ */
+export declare function mergeAuthoredSeries(derived: ChartSeriesBinding[], authoredSeries: unknown): MergedChartSeries[];
+/**
+ * Merge an authored chart config's PRESENTATION onto the series and axes the
+ * dataset selection derived — the one place that happens for a surface whose
+ * axes are spec `ChartAxis` OBJECTS (#4229).
+ *
+ * The series half is {@link mergeAuthoredSeries}; see it for the match rule and
+ * for why membership is safe. The axes half reads `xAxis` / `yAxis` through
+ * {@link axisPresentation}, which is why a surface spelling those as bare NAME
+ * strings must call `mergeAuthoredSeries` directly instead (file header).
+ *
+ * @param derived the bindings {@link buildChartSeries} produced from the selection
+ * @param raw the authored chart config (anything, incl. absent)
+ * @returns the merged series, plus the presentation-only axes to spread onto
+ *   the chart schema (absent when the author declared none)
+ */
+export declare function mergeAuthoredPresentation(derived: ChartSeriesBinding[], raw: unknown): {
+    series: MergedChartSeries[];
+    axes: Record<string, unknown>;
+};
+/**
+ * Lower an authored chart config's CHROME (spec `ChartConfigSchema` /
+ * `ReportChartSchema` — the same keys on both) onto the chart schema a
+ * dataset-bound surface hands the renderer.
+ *
+ * ## Why this is a whitelist and not a spread
+ *
+ * Until #3135 NONE of a dashboard widget's `chartConfig` reached the renderer:
+ * the widget read `options` and nothing else, so an author who wrote
+ * `showLegend: false` still got a legend and one who wrote `true` only got one
+ * because "on" is the renderer's default. #3135 lowered that single flag and
+ * left the rest declared and inert. objectstack#7016 lowered the rest of the
+ * keys that are actually DELIVERED, admitting a key only when both of these
+ * hold:
+ *
+ *  1. **The chart block draws it end to end.** `{ type: 'chart' }` resolves to
+ *     `ChartRenderer` → `AdvancedChartImpl`, which draws `title`/`subtitle` in
+ *     its ChartFrame, turns `description` into the chart container's
+ *     `role="img"` + `aria-label`, applies `height` as that container's inline
+ *     height, reads `colors` as the positional palette, prints
+ *     `showDataLabels` as a Recharts `LabelList`, draws `annotations` as
+ *     ReferenceLine/ReferenceArea and honours `interaction` as the tooltip
+ *     toggle plus `Brush`. Forwarding a key the renderer ignores would only
+ *     move declared-but-not-delivered one layer down, which is the failure this
+ *     exists to remove.
+ *  2. **It does not fight the dataset derivation.** `type` stays out: the
+ *     calling surface's own type already picks the chart family, which is the
+ *     dataset path's chart-family channel.
+ *
+ * `aria` is the one declared key with **no reader at all**: `AdvancedChartImpl`
+ * has no `aria` prop, and `SchemaRenderer`'s ARIA injection reads the FLAT
+ * `ariaLabel`/`ariaDescribedBy`/`role`, never a nested `aria` object. It is
+ * therefore left unforwarded on purpose (criterion 1) rather than papered over
+ * with a caller-side flattening that would also collide with the accessible
+ * name `description` already sets — reported back to objectstack#5175's
+ * narrowing half instead.
+ *
+ * `title` IS emitted here. A caller that paints the title itself (the report
+ * renderer's own `h3` above the chart) must drop it from the result, or the
+ * chart draws a second one.
+ *
+ * @param raw the authored chart config (anything, incl. absent)
+ * @param fieldCategoryColors per-category colours resolved from the category
+ *   dimension's own select/lookup option colours, merged UNDER an explicit
+ *   author map (see the `colors` note below)
+ * @returns only the keys that resolved, so the caller can spread it over the
+ *   derived chart schema and every undeclared key keeps the renderer's default
+ */
+export declare function chartConfigPresentation(raw: unknown, fieldCategoryColors?: Record<string, string> | null): Record<string, unknown>;