@object-ui/core 17.5.0 → 17.6.0

package/dist/registry/Registry.d.ts

@@ -5,22 +5,30 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SchemaNode } from '../types/index.js';
+import type { ComponentInput } from '@object-ui/types';
 export type ComponentRenderer<T = any> = T;
-export type ComponentInput = {
-    name: string;
-    type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
-    label?: string;
-    defaultValue?: any;
-    required?: boolean;
-    enum?: string[] | {
-        label: string;
-        value: any;
-    }[];
-    description?: string;
-    advanced?: boolean;
-    inputType?: string;
-};
+/**
+ * What a registration DECLARES about one authorable prop.
+ *
+ * This is the declaration the component registrations themselves import, so it
+ * is the one an author's manifest is ultimately built from — and it is now
+ * RE-EXPORTED from `@object-ui/types` rather than restated here
+ * (objectui#4972), the disposition objectui#4580 ruled for the identical
+ * shape: *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, and `src/types/index.ts` re-exports `SchemaNode`
+ * from there the same way.
+ *
+ * The copy this replaces had ALREADY moved, which is why the card is not
+ * hypothetical: it carried nine keys while `base.ts` carried thirteen, so
+ * `min` / `max` / `step` / `placeholder` were missing from *the copy every
+ * registration actually imports*. Those four keys were therefore unwritable at
+ * any real registration — a plain TS error — while `ComponentInputSchema` (the
+ * zod schema) and `ComponentMeta.inputs` both accepted them. The publication
+ * face advertised four keys the authoring face rejected; the divergence was
+ * dormant only because no registration had tried to write one yet.
+ */
+export type { ComponentInput } from '@object-ui/types';
 export type ComponentMeta = {
     label?: string;
     icon?: string;
@@ -45,7 +53,11 @@ export type ComponentMeta = {
     skipFallback?: boolean;
     /**
      * How a HOST must associate its own visible label with what this component
-     * renders (objectui#3961). Read by the form renderer; absent ⇒ `'control'`.
+     * renders (objectui#3961, extended by objectui#4857). Read by the form
+     * renderer; absent ⇒ `'control'`. This closed three-value vocabulary is the
+     * single repo-wide answer to "how does a host learn what a widget will
+     * render" (maintainer ruling of 2026-08-17, joint with objectui#4871) — no
+     * host may keep a local variant of it.
      *
      * - `'control'` — the component's outermost rendered element is a LABELABLE
      *   HTML element (`input` / `textarea` / `select` / `button` / …), so the host
@@ -58,7 +70,18 @@ export type ComponentMeta = {
      *   nothing and contributes no accessible name (`HTMLLabelElement.control` is
      *   `null`) — so the host must instead give its label an `id` and hand the
      *   component `aria-labelledby`, which associates by IDREF and works on any
-     *   element.
+     *   element. The COMPONENT consumes those keys on its own surface.
+     * - `'display'` — the rendered surface is a pure display in EVERY state:
+     *   there is no focusable control and the component itself spreads nothing
+     *   (computed / system-generated values such as `formula` / `summary` /
+     *   `auto_number` / `vector`). The host must not emit a `<label for>` at all
+     *   — no labelable element will ever exist for it to reach, in the editable
+     *   state as much as the readonly one — and instead wraps the component's
+     *   output in the host's own container carrying the field id,
+     *   `aria-labelledby`, `aria-describedby` and `role="group"` (the
+     *   objectui#4788 channel, driven by this declaration rather than by
+     *   `readonly` alone). Unlike `'group'`, the WIDGET is not expected to
+     *   consume anything: the host's wrapper is the named surface.
      *
      * This is a DECLARATION, not a guess: the host cannot infer it from the DOM a
      * widget happens to render, and a widget that fails to declare it falls back
@@ -66,10 +89,9 @@ export type ComponentMeta = {
      * label-association tests (objectui#3952) instead of silently producing an
      * unlabelled group.
      */
-    labelling?: 'control' | 'group';
+    labelling?: 'control' | 'group' | 'display';
     inputs?: ComponentInput[];
     defaultProps?: Record<string, any>;
-    defaultChildren?: SchemaNode[];
     examples?: Record<string, any>;
     isContainer?: boolean;
     resizable?: boolean;

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, 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

@@ -11,4 +11,4 @@ export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, genera
 // 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';
+generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine.js';

package/dist/types/index.d.ts

@@ -30,24 +30,103 @@
  * 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, and core's own entry surface is unchanged (`dist/index.d.ts`
- * is byte-identical across the change — measured, both rounds).
+ * 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';
-import type { SchemaNode } from '@object-ui/types';
 /**
- * ⛔ Deliberately NOT reconciled with `@object-ui/types`' `ComponentRendererProps`
- * (objectui#4594). The two declarations differ — types' is generic
- * (`< TSchema extends BaseSchema = BaseSchema >`), this one is not — but that
- * card measured **zero consumers** of this declaration, so reconciling it here
- * would be an unmeasured change riding a card that was scoped to `SchemaNode`.
- * It stays dual-declared until #4594 is dispatched on its own evidence.
+ * 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 interface ComponentRendererProps {
-    schema: SchemaNode;
-    [key: string]: any;
-}
+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>;