@matthieumordrel/chart-studio 0.2.5 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ Use this if you already have your own design system or chart renderer.
 You get:
 
 - `useChart`
-- optional `schema` via `defineChartSchema`
+- optional `schema` via `defineDataset(...).chart(...)`
 - transformed chart data
 - filtering, grouping, metrics, and time bucketing logic
 
@@ -98,9 +98,344 @@ export function JobsChart() {
 ## How It Works
 
 1. Pass your raw data to `useChart()`.
-2. Add an optional `schema` with `defineChartSchema<Row>()...` when you need labels, type overrides, derived columns, or control restrictions (allowed metrics, groupings, chart types, etc.).
+2. Add an optional `schema` with `defineDataset<Row>().chart(...)` when you need labels, type overrides, derived columns, or control restrictions (allowed metrics, groupings, chart types, etc.).
 3. Either render your own UI from the returned state, or use the components from `@matthieumordrel/chart-studio/ui`.
 
+## Stable Single-Chart Contract
+
+For the simple case, the public contract is:
+
+- `useChart({ data })` stays the zero-config path
+- `useChart({ data, schema })` is the explicit single-chart path
+- `defineDataset<Row>().chart(...)` is the single explicit way to build that schema
+- `.columns(...)` is the authoring entry point: override raw fields, exclude fields, and add derived columns
+- raw fields you do not mention in `.columns(...)` still infer normally unless you exclude them
+- `xAxis`, `groupBy`, `filters`, `metric`, `chartType`, `timeBucket`, and `connectNulls` restrict that one chart's public controls
+- `inputs` is an additive escape hatch for externally controlled data-scope state; it does not replace the simple `useChart({ data })` or `useChart({ data, schema })` path
+- pass the builder directly to `useChart(...)`, or call `.build()` if you need the plain schema object
+
+## Choose the Right Boundary
+
+There are two different scaling paths in `chart-studio`:
+
+### Independent dataset(s)
+
+Stay on the single-chart path when each chart reads one flat row shape, even if
+one screen renders several unrelated charts.
+
+Use:
+
+- `useChart({ data })` for zero-config charts
+- `defineDataset<Row>().chart(...)` when one chart owns its own explicit contract
+- `defineDataset<Row>()` when several charts should reuse one row contract
+- `useChart({ sources: [...] })` only for source-switching inside one chart
+
+Stop here when:
+
+- charts do not need relationship-aware shared filters
+- datasets are already flattened for the charts that consume them
+- each chart can execute honestly against one dataset at a time
+
+### Related dashboard
+
+Move up to the model + dashboard path when several datasets are structurally
+related and you want shared filters, referential validation, or safe
+lookup-preserving cross-dataset fields.
+
+Recommended path for new dashboard work:
+
+1. `defineDataModel().dataset(...).infer(...)`
+2. `model.chart(...)` for lookup-preserving charts
+3. `model.materialize(...)` only when the chart grain changes
+4. `defineDashboard(model)`
+5. `useDashboard(...)`
+
+## Authoring Layers
+
+### 1. Single-chart explicit path
+
+Use `defineDataset<Row>().chart(...)` when one chart owns its own explicit contract:
+
+```tsx
+const schema = defineDataset<Job>()
+  .columns((c) => [
+    c.date('createdAt'),
+    c.category('ownerName'),
+    c.number('salary')
+  ])
+  .chart()
+  .xAxis((x) => x.allowed('createdAt'))
+  .metric((m) => m.aggregate('salary', 'sum'))
+
+const chart = useChart({ data: jobs, schema })
+```
+
+This is the single explicit path for declaring a chart schema. The dataset
+owns the column contract, and `.chart(...)` layers chart-specific control
+restrictions on top.
+
+### 2. Dataset-first reuse
+
+Use `defineDataset<Row>()` when several charts should share one `.columns(...)`
+contract and one optional declared key:
+
+```tsx
+import { defineDataset, useChart } from '@matthieumordrel/chart-studio'
+
+const jobs = defineDataset<Job>()
+  .key('id')
+  .columns((c) => [
+    c.field('id'),
+    c.field('ownerId'),
+    c.date('createdAt', { label: 'Created' }),
+    c.number('salary', { format: 'currency' }),
+    c.derived.category('salaryBand', {
+      label: 'Salary Band',
+      accessor: (row) => (row.salary >= 100_000 ? 'High' : 'Base')
+    })
+  ])
+
+const jobsByMonth = jobs
+  .chart('jobsByMonth')
+  .xAxis((x) => x.allowed('createdAt').default('createdAt'))
+  .groupBy((g) => g.allowed('salaryBand'))
+  .metric((m) => m.count().aggregate('salary', 'sum'))
+
+const chart = useChart({ data: jobsData, schema: jobsByMonth })
+```
+
+Rules for the dataset-first path:
+
+- dataset `.columns(...)` is the canonical reusable meaning of columns
+- `dataset.chart(...)` provides the chart-definition surface for control restrictions
+- `dataset.chart(...)` inherits dataset columns, so charts do not reopen `.columns(...)`
+- declared dataset keys can be validated at runtime with `dataset.validateData(data)` or `validateDatasetData(dataset, data)`
+
+### 3. Model-level linked data
+
+Use `defineDataModel()` when datasets are related and you want the model to own
+safe inference, validation, and reusable dashboard semantics:
+
+```tsx
+import {
+  defineDataModel,
+  defineDataset,
+} from '@matthieumordrel/chart-studio'
+
+const hiringModel = defineDataModel()
+  .dataset('jobs', defineDataset<Job>()
+    .key('id')
+    .columns((c) => [
+      c.date('createdAt'),
+      c.category('status'),
+      c.number('salary', { format: 'currency' }),
+    ]))
+  .dataset('owners', defineDataset<Owner>()
+    .key('id')
+    .columns((c) => [
+      c.category('name', { label: 'Owner' }),
+      c.category('region'),
+    ]))
+  .infer({
+    relationships: true,
+    attributes: true,
+  })
+
+const jobsByOwner = hiringModel.chart('jobsByOwner', (chart) =>
+  chart
+    .xAxis((x) => x.allowed('jobs.createdAt', 'jobs.owner.name').default('jobs.owner.name'))
+    .filters((f) => f.allowed('jobs.status', 'jobs.owner.region'))
+    .metric((m) =>
+      m
+        .aggregate('jobs.salary', 'avg')
+        .defaultAggregate('jobs.salary', 'avg'))
+    .chartType((t) => t.allowed('bar', 'line').default('bar'))
+)
+
+hiringModel.validateData({
+  jobs: jobsData,
+  owners: ownersData,
+})
+```
+
+What the model can infer today:
+
+- obvious one-hop lookup relationships from one dataset into another
+- reusable shared-filter attributes backed by those relationships
+- safe lookup-preserving model chart fields such as `jobs.owner.name`
+- the base dataset for a model chart when every qualified field is anchored to
+  the same dataset id
+
+How to prepare data for safe inference:
+
+- declare one real key per dataset with `.key(...)`; single-column lookup keys
+  work best
+- for the common case, use lookup datasets keyed by `id` and foreign keys named
+  `<singularDatasetId>Id` such as `ownerId`, `teacherId`, or `customerId`
+- if a lookup key is already named `somethingId`, that same field name can be
+  inferred as a foreign key candidate on related datasets
+- give lookup datasets a visible label-like column such as `name`, `title`, or
+  `label` when you want inferred shared filters to feel good by default
+- leaving a raw field out of `.columns(...)` is not exclusion; use
+  `exclude(...)` only when you want that field removed from the chart contract
+
+Important limits of the current model layer:
+
+- inference is conservative; ambiguous candidates are ignored until you declare
+  `.relationship(...)` or suppress a false positive with
+  `.infer({ exclude: ['datasetId.columnId'] })`
+- many-to-many stays explicit through `association(...)`
+- model-aware charts allow one lookup hop only; they do not infer row-expanding
+  traversal
+- if you use unqualified field ids, or fields anchored to multiple datasets,
+  add `.from('datasetId')`
+- `validateData(...)` hard-fails on duplicate declared keys, orphan foreign keys, and malformed association edges
+- charts still execute against one flat dataset at a time
+- lookup-preserving model charts compile into the same explicit runtime core;
+  expanded chart grains still require `model.materialize(...)`
+- explicit `.relationship(...)`, `.attribute(...)`, and `.association(...)`
+  remain available when inference is not enough
+- linked metrics do not exist yet
+
+### 4. Materialized views
+
+Use `model.materialize(...)` when one chart truly needs a flat cross-dataset
+analytic grain:
+
+```tsx
+const jobsWithOwner = hiringModel.materialize('jobsWithOwner', (m) =>
+  m
+    .from('jobs')
+    .join('owner', { relationship: 'jobs.ownerId -> owners.id' })
+    .grain('job')
+)
+
+const rows = jobsWithOwner.materialize({
+  jobs: jobsData,
+  owners: ownersData,
+})
+
+const chart = useChart({
+  data: rows,
+  schema: jobsWithOwner
+    .chart('jobsByOwner')
+    .xAxis((x) => x.allowed('ownerName').default('ownerName'))
+    .groupBy((g) => g.allowed('ownerRegion').default('ownerRegion'))
+    .metric((m) => m.aggregate('salary', 'sum').defaultAggregate('salary', 'sum')),
+})
+```
+
+If you need a many-to-many chart grain such as `job-skill`, declare an explicit
+`association(...)` on the model and then expand through it with
+`.throughAssociation(...).grain(...)`.
+
+Rules for materialized views:
+
+- `materialize(...)` is explicit; the model does not become a hidden query engine
+- prefer `model.chart(...)` for safe lookup-preserving fields; reach for `materialize(...)` when the chart grain actually changes
+- `grain(...)` is required so the output row grain stays visible
+- `.join(...)` is for lookup-style joins that preserve the base grain
+- `.throughRelationship(...)` and `.throughAssociation(...)` are the explicit row-expanding paths
+- many-to-many flattening stays visible because `association(...)` and `throughAssociation(...)` are both opt-in
+- related-table columns reuse the linked dataset definitions, so you do not need repeated per-dataset derived columns like `ownerName`, `ownerRegion`, or `skillName`
+- the materialized view is chartable like a normal dataset and exposes `materialize(data)` for explicit reuse and caching
+
+### 5. Dashboard composition
+
+Use `defineDashboard(model)` when several reusable charts belong to one
+dashboard:
+
+```tsx
+import {
+  DashboardProvider,
+  defineDashboard,
+  useDashboard,
+  useDashboardChart,
+} from '@matthieumordrel/chart-studio'
+
+const hiringDashboard = defineDashboard(hiringModel)
+  .chart('jobsByOwner', jobsByOwner)
+  .sharedFilter('owner')
+  .build()
+
+function HiringOverview() {
+  const dashboard = useDashboard({
+    definition: hiringDashboard,
+    data: {
+      jobs: jobsData,
+      owners: ownersData,
+    },
+  })
+
+  return (
+    <DashboardProvider dashboard={dashboard}>
+      <HiringChart />
+    </DashboardProvider>
+  )
+}
+
+function HiringChart() {
+  const jobsChart = useDashboardChart(hiringDashboard, 'jobsByOwner')
+
+  return (
+    <Chart chart={jobsChart}>
+      <ChartCanvas />
+    </Chart>
+  )
+}
+```
+
+Rules for dashboard composition:
+
+- `defineDashboard(model)` is intentionally thin: chart registration, shared-filter selection, and optional dashboard-local shared filters
+- dashboard charts may come from `dataset.chart(...)`, `model.chart(...)`, or `model.materialize(...).chart(...)`
+- chart registration is explicit by id
+- `useDashboard(...)` is the runtime boundary; it resolves model-aware charts and explicit materialized views against real data
+- pass the explicit dashboard runtime into dashboard hooks, or inside a matching `DashboardProvider` pass the dashboard definition
+- `useDashboardChart(...)` resolves the reusable chart by id and keeps React in charge of placement
+- `useDashboardDataset(...)` exposes the globally filtered rows for non-chart consumers like KPI cards or tables
+
+### 6. Shared dashboard filters
+
+Shared dashboard filters layer on top of dashboard composition.
+
+Reuse model-level relationship semantics when the same filter concept should
+work across several dashboards:
+
+```tsx
+const dashboard = defineDashboard(hiringModel)
+  .chart('jobsByOwner', jobsByOwner)
+  .sharedFilter('owner')
+```
+
+Add one-off dashboard-local filters when the concept is specific to one
+dashboard:
+
+```tsx
+const dashboard = defineDashboard(hiringModel)
+  .chart('jobsByOwner', jobsByOwner)
+  .sharedFilter('status', {
+    kind: 'select',
+    source: { dataset: 'jobs', column: 'status' },
+  })
+  .sharedFilter('activityDate', {
+    kind: 'date-range',
+    targets: [
+      { dataset: 'jobs', column: 'createdAt' },
+    ],
+  })
+```
+
+Rules for shared dashboard filters:
+
+- `sharedFilter('owner')` can reuse either an inferred model attribute or an explicit one
+- the model may infer useful attributes, but the dashboard still decides which ones become visible shared filters
+- shared filters are explicit; nothing is guessed from chart configs
+- shared filters narrow dataset slices before chart-local `useChart(...)` filters run
+- local and global filters compose by intersection
+- when a shared filter targets the same chart-local column, the dashboard owns that filter for that chart by default
+- cross-dataset ambiguity requires an explicit model `attribute(...)` or explicit target choice
+
 ## Column Types
 
 | Type       | What it is for                          |
@@ -112,20 +447,21 @@ export function JobsChart() {
 
 ## Declarative Schema and Control Restrictions
 
-If you want to expose only a subset of groupings, metrics, chart types, or axes, use the fluent `defineChartSchema<Row>()` builder:
+If you want to expose only a subset of groupings, metrics, chart types, or axes, use the fluent `defineDataset<Row>().chart(...)` builder:
 
 ```tsx
-import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
+import { defineDataset, useChart } from '@matthieumordrel/chart-studio'
 
 type Row = { periodEnd: string; segment: string; revenue: number; netIncome: number }
 
-const schema = defineChartSchema<Row>()
+const schema = defineDataset<Row>()
   .columns((c) => [
     c.date('periodEnd', { label: 'Period End' }),
     c.category('segment'),
     c.number('revenue'),
     c.number('netIncome')
   ])
+  .chart()
   .xAxis((x) => x.allowed('periodEnd'))
   .groupBy((g) => g.allowed('segment'))
   .metric((m) =>
@@ -153,7 +489,7 @@ Why this pattern:
 If you want to render your own UI or your own charting library, use only the core state:
 
 ```tsx
-import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
+import { defineDataset, useChart } from '@matthieumordrel/chart-studio'
 
 type Job = {
   dateAdded: string
@@ -161,12 +497,13 @@ type Job = {
   salary: number
 }
 
-const jobSchema = defineChartSchema<Job>()
+const jobSchema = defineDataset<Job>()
   .columns((c) => [
     c.date('dateAdded', { label: 'Date Added' }),
     c.category('ownerName', { label: 'Consultant' }),
     c.number('salary', { label: 'Salary' })
   ])
+  .chart()
 
 export function JobsChartHeadless({ data }: { data: Job[] }) {
   const chart = useChart({ data, schema: jobSchema })
@@ -322,10 +659,23 @@ Only for the UI layer. The headless core does not require it.
 
 ### Can I use multiple datasets?
 
-Yes:
+Yes, but there are two different meanings:
+
+- independent datasets: use separate `useChart(...)` calls, or `useChart({ sources: [...] })` when one chart should switch between flat sources
+- related datasets: use `defineDataModel().dataset(...).infer(...)`, then `model.chart(...)` for safe lookup-preserving charts
+- explicit expanded grains: use `model.materialize(...)`
+- screen-level composition and shared state: use `defineDashboard(model)` plus `useDashboard(...)`
+
+The current chart runtime still executes one flat dataset at a time. Multi-source
+source-switching is separate from linked data models, explicit materialized
+views, and dashboard composition.
+
+If you are starting fresh with a dashboard, use the model-first path:
+`defineDataModel(...)`, `model.chart(...)` / `model.materialize(...)`,
+`defineDashboard(...)`, and `useDashboard(...)`.
 
 ```tsx
-import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
+import { defineDataset, useChart } from '@matthieumordrel/chart-studio'
 
 const chart = useChart({
   sources: [
@@ -333,14 +683,47 @@ const chart = useChart({
       id: 'jobs',
       label: 'Jobs',
       data: jobs,
-      schema: defineChartSchema<Job>()
+      schema: defineDataset<Job>()
         .columns((c) => [c.date('dateAdded', { label: 'Date Added' })])
+        .chart()
     },
     { id: 'candidates', label: 'Candidates', data: candidates }
   ]
 })
 ```
 
+Each source may use `defineDataset<Row>().chart(...)`. The chart still reads one
+active source at a time, so this is not dashboard composition and not
+cross-dataset execution.
+
+### Can outside state drive one chart's filters or date range?
+
+Yes. Use `inputs` for externally controlled data-scope state:
+
+```tsx
+const chart = useChart({
+  data: jobs,
+  schema,
+  inputs: {
+    filters,
+    onFiltersChange: setFilters,
+    referenceDateId,
+    onReferenceDateIdChange: setReferenceDateId,
+    dateRange,
+    onDateRangeChange: setDateRange
+  }
+})
+```
+
+Rules:
+
+- `inputs` only covers data-scope state: filters, reference date, and date range
+- presentation controls such as `xAxis`, `groupBy`, `metric`, and `chartType` stay chart-local
+- `dateRange` is `{ preset, customFilter }`
+- when an input is controlled, chart setters request changes through the matching callback
+- `chart.filters` and related date state are always the sanitized effective state for the active source
+- this still does not create a dashboard runtime or shared state between charts; use `defineDashboard()` for that
+
 ### What chart types are available?
 
 - date X-axis: `bar`, `line`, `area`
@@ -382,11 +765,18 @@ There is currently no built-in support for drill-down, click-to-filter, brush se
 
 ### Multi-dataset composition
 
-Each chart instance operates on a single flat dataset. Overlaying series from different schemas (e.g. revenue on the left Y-axis and headcount on the right) would require separate chart instances today. Dual-axis and cross-dataset composition are not yet supported.
+Dashboard composition and shared dashboard filters are now available, but each
+chart instance still operates on one flat dataset at a time. Overlaying series
+from different schemas (e.g. revenue on the left Y-axis and headcount on the
+right) would require separate chart instances today. Dual-axis cross-dataset
+execution, automatic denormalization, and linked metrics are not yet supported.
 
 ### Schema Builder Ergonomics
 
-`defineChartSchema<Row>()` now returns one fluent builder that you pass directly to `useChart(...)` or `inferColumnsFromData(...)`. That keeps the public API strongly typed while improving IntelliSense for raw field ids, derived columns, and control restrictions.
+`defineDataset<Row>()` owns the reusable `.columns(...)` contract, and
+`defineDataset<Row>().chart(...)` is the single explicit path for declaring a
+chart schema. Both feed the same chart-definition surface that you pass directly
+to `useChart(...)` or `inferColumnsFromData(...)`.
 
 ## Release
 

package/dist/core/chart-builder-controls.mjs

@@ -0,0 +1,141 @@
+import { isSameMetric, normalizeMetricAllowances } from "./metric-utils.mjs";
+//#region src/core/chart-builder-controls.ts
+const SELECTABLE_CONTROL_CONFIG = Symbol("chart-schema-selectable-control-config");
+const METRIC_CONTROL_CONFIG = Symbol("chart-schema-metric-config");
+function uniqueValues(values) {
+	if (!values || values.length === 0) return;
+	return [...new Set(values)];
+}
+function sanitizeSelectableControlConfig(config, supportsDefault) {
+	const allowed = uniqueValues(config.allowed);
+	let hidden = uniqueValues(config.hidden);
+	if (allowed && hidden) {
+		const allowedSet = new Set(allowed);
+		hidden = hidden.filter((option) => allowedSet.has(option));
+	}
+	let nextDefault = supportsDefault ? config.default : void 0;
+	if (nextDefault !== void 0) {
+		if (allowed && !allowed.includes(nextDefault)) nextDefault = void 0;
+		if (nextDefault !== void 0 && hidden?.includes(nextDefault)) nextDefault = void 0;
+	}
+	const nextConfig = {};
+	if (allowed && allowed.length > 0) nextConfig.allowed = allowed;
+	if (hidden && hidden.length > 0) nextConfig.hidden = hidden;
+	if (nextDefault !== void 0) nextConfig.default = nextDefault;
+	return nextConfig;
+}
+function createSelectableControlBuilder(config = {}, supportsDefault) {
+	const nextConfig = sanitizeSelectableControlConfig(config, supportsDefault);
+	return {
+		allowed(...options) {
+			return createSelectableControlBuilder({
+				...nextConfig,
+				allowed: options
+			}, supportsDefault);
+		},
+		hidden(...options) {
+			return createSelectableControlBuilder({
+				...nextConfig,
+				hidden: [...nextConfig.hidden ?? [], ...options]
+			}, supportsDefault);
+		},
+		default(option) {
+			return createSelectableControlBuilder({
+				...nextConfig,
+				default: option
+			}, supportsDefault);
+		},
+		[SELECTABLE_CONTROL_CONFIG]: nextConfig
+	};
+}
+function uniqueMetrics(metrics) {
+	if (!metrics || metrics.length === 0) return;
+	const unique = [];
+	for (const metric of metrics) if (!unique.some((candidate) => isSameMetric(candidate, metric))) unique.push(metric);
+	return unique;
+}
+function sanitizeMetricConfig(config) {
+	const allowed = config.allowed && config.allowed.length > 0 ? [...config.allowed] : void 0;
+	let hidden = uniqueMetrics(config.hidden);
+	const expandedAllowed = normalizeMetricAllowances(allowed);
+	if (expandedAllowed && hidden) hidden = hidden.filter((metric) => expandedAllowed.some((allowedMetric) => isSameMetric(allowedMetric, metric)));
+	let nextDefault = config.default;
+	if (nextDefault) {
+		const defaultMetric = nextDefault;
+		if (expandedAllowed && !expandedAllowed.some((metric) => isSameMetric(metric, defaultMetric))) nextDefault = void 0;
+		if (nextDefault) {
+			const visibleDefault = nextDefault;
+			if (hidden?.some((metric) => isSameMetric(metric, visibleDefault))) nextDefault = void 0;
+		}
+	}
+	const nextConfig = {};
+	if (allowed && allowed.length > 0) nextConfig.allowed = allowed;
+	if (hidden && hidden.length > 0) nextConfig.hidden = hidden;
+	if (nextDefault) nextConfig.default = nextDefault;
+	return nextConfig;
+}
+function createMetricBuilder(config = {}) {
+	const nextConfig = sanitizeMetricConfig(config);
+	return {
+		count() {
+			return createMetricBuilder({
+				...nextConfig,
+				allowed: [...nextConfig.allowed ?? [], { kind: "count" }]
+			});
+		},
+		aggregate(columnId, firstAggregate, ...restAggregates) {
+			const aggregates = [firstAggregate, ...restAggregates];
+			const selection = restAggregates.length === 0 ? firstAggregate : aggregates;
+			return createMetricBuilder({
+				...nextConfig,
+				allowed: [...nextConfig.allowed ?? [], {
+					kind: "aggregate",
+					columnId,
+					aggregate: selection
+				}]
+			});
+		},
+		hideCount() {
+			return createMetricBuilder({
+				...nextConfig,
+				hidden: [...nextConfig.hidden ?? [], { kind: "count" }]
+			});
+		},
+		hideAggregate(columnId, firstAggregate, ...restAggregates) {
+			const aggregates = [firstAggregate, ...restAggregates];
+			return createMetricBuilder({
+				...nextConfig,
+				hidden: [...nextConfig.hidden ?? [], ...aggregates.map((aggregate) => ({
+					kind: "aggregate",
+					columnId,
+					aggregate
+				}))]
+			});
+		},
+		defaultCount() {
+			return createMetricBuilder({
+				...nextConfig,
+				default: { kind: "count" }
+			});
+		},
+		defaultAggregate(columnId, aggregate) {
+			return createMetricBuilder({
+				...nextConfig,
+				default: {
+					kind: "aggregate",
+					columnId,
+					aggregate
+				}
+			});
+		},
+		[METRIC_CONTROL_CONFIG]: nextConfig
+	};
+}
+function getSelectableControlConfig(builder) {
+	return builder[SELECTABLE_CONTROL_CONFIG];
+}
+function getMetricBuilderConfig(builder) {
+	return builder[METRIC_CONTROL_CONFIG];
+}
+//#endregion
+export { createMetricBuilder, createSelectableControlBuilder, getMetricBuilderConfig, getSelectableControlConfig };