react-semaphor 0.1.544 → 0.1.545

package/dist/surfboard/index.js

@@ -1,4 +1,4 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-Df7VpRVW.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-DUtuUL_5.js";
 import { C as f, E as D } from "../chunks/table-settings-CLZocegs.js";
 export {
   f as CONTROL_CARD_DEFAULT_VALUE,

package/dist/types/briefings/attachment-outcomes.d.ts

@@ -4,7 +4,7 @@ import { BriefingAttachmentFormat } from './index.js';
  * RA-D14). The app decides the code and writes the customer line; the run
  * card reads both back from the run.
  */
-export declare const BRIEFING_ATTACHMENT_OMISSION_CODES: readonly ["PDF_ROW_LIMIT_EXCEEDED", "PDF_SIZE_LIMIT_EXCEEDED", "TABLE_COMPLETENESS_UNVERIFIED", "CARD_QUERY_FAILED", "RENDER_NOT_READY", "RENDER_TIMED_OUT", "EXPORT_JOB_FAILED", "ATTACHMENT_UNAVAILABLE", "EXCEL_LIMIT_EXCEEDED", "EXPORT_ROW_LIMIT_EXCEEDED", "EXPORT_COUNT_UNAVAILABLE", "EXPORT_NO_ROWS"];
+export declare const BRIEFING_ATTACHMENT_OMISSION_CODES: readonly ["PDF_ROW_LIMIT_EXCEEDED", "PDF_SIZE_LIMIT_EXCEEDED", "TABLE_COMPLETENESS_UNVERIFIED", "CARD_QUERY_FAILED", "RENDER_NOT_READY", "RENDER_TIMED_OUT", "EXPORT_JOB_FAILED", "ATTACHMENT_UNAVAILABLE", "EXCEL_LIMIT_EXCEEDED", "EXPORT_ROW_LIMIT_EXCEEDED", "EXPORT_COUNT_UNAVAILABLE", "EXPORT_NO_ROWS", "IMAGE_TOO_LARGE"];
 export type BriefingAttachmentOmissionCode = (typeof BRIEFING_ATTACHMENT_OMISSION_CODES)[number];
 /** One left-out attachment, as recorded on the run and read by every channel. */
 export type BriefingOmittedAttachment = {

package/dist/types/briefings/attachments.d.ts

@@ -1,4 +1,5 @@
 import { BriefingAttachment, BriefingAttachmentFormat } from './index.js';
+import { ExportFileFormat } from '../shared/format-utils/exporters/export-file-format.js';
 import { TCard } from '../lib/types/common-types.js';
 export type BriefingCardAttachmentCapability = {
     formats: BriefingAttachmentFormat[];
@@ -11,19 +12,45 @@ export declare function getBriefingCardAttachmentCapability(card: TCard): Briefi
  * every row up to the export cap.
  */
 export declare function isBriefingTableExportCardType(cardType: string | undefined): boolean;
+/** How a run makes an attachment (PNG exports SPEC §2.7). */
+export type BriefingAttachmentProduction = 
+/** Drawn by the renderer from the print view (PDF, PNG, and CSV of a card that is not a table or Matrix). */
+{
+    kind: 'rendered';
+    format: 'pdf' | 'png' | 'csv';
+}
+/** A Matrix card's PDF, built from the Matrix capture. */
+ | {
+    kind: 'matrix_pdf';
+}
+/** A background export job: CSV and Excel of Table, Detail Table and Matrix cards. */
+ | {
+    kind: 'export_job';
+    format: ExportFileFormat;
+};
 /**
- * Attachments a background export job makes before a run is finalized
- * (Excel exports SPEC §3.4, §3.5): a card's data file (CSV or Excel) of a
- * Matrix with its capture, a Table or a Detail Table. Every other attachment
- * renders. Read by preparation, release, delivery access and the page route
- * alike, so they always agree on which attachments a job makes.
+ * How the run makes this attachment. The only place that decides it: a PNG
+ * is always rendered (a Matrix PNG too), a Matrix PDF comes from the Matrix
+ * capture, and a data file (CSV or Excel) of a Matrix with its capture, a
+ * Table or a Detail Table is a background export job (Excel exports SPEC
+ * §3.4, §3.5). Read by preparation, release, delivery access, the page route
+ * and the renderer adapter alike, so they always agree.
  */
+export declare function briefingAttachmentProduction(attachment: BriefingAttachment): BriefingAttachmentProduction;
+/** Attachments a background export job makes before a run is finalized. */
 export declare function briefingAttachmentNeedsExportJob(attachment: BriefingAttachment): boolean;
+export type BriefingAttachmentFileTraits = {
+    label: string;
+    extension: string;
+    contentType: string;
+};
+/** An attachment file's name, extension and content type: rendered files and data files have one owner each. */
+export declare function briefingAttachmentFileTraits(format: BriefingAttachmentFormat): BriefingAttachmentFileTraits;
 export declare function getBriefingCardAttachmentFormats(input: {
     cardType: string;
     allowDownload?: boolean;
 }): BriefingAttachmentFormat[];
-/** The name customers read for an attachment format: PDF, CSV or Excel. */
+/** The name customers read for an attachment format: PDF, PNG image, CSV or Excel. */
 export declare function briefingAttachmentFormatLabel(format: BriefingAttachmentFormat): string;
 export declare function getDefaultBriefingCardAttachmentFormat(input: {
     cardType: string;

package/dist/types/briefings/index.d.ts

@@ -2,11 +2,10 @@ import { NumericCanonicalFormat, NumericPresentationTarget, PresentationExecutio
 import { BriefingAppearanceSpec, BriefingFragments, BriefingThemeOverrides } from './presentation-contract.js';
 import { MatrixConfig } from '../shared/analytics-protocol/index.js';
 import { CsvEncoding } from '../shared/format-utils/exporters/csv-utils.js';
-import { ExportFileFormat } from '../shared/format-utils/exporters/export-file-format.js';
 export { captureMatrixExport, buildMatrixDeliveryEnvelope, matrixDeliveryPayloadSchema, matrixDeliveryQuerySchema, type MatrixLayoutReadResult } from '../shared/dashboard-authoring/matrix-delivery.js';
 export declare const BRIEFING_KIND: "BRIEFING";
 export { DEFAULT_BRIEFING_SCHEDULE, briefingScheduleMonths, briefingScheduleDayOccurs, briefingScheduleShortMonths, buildBriefingScheduleExpr, canonicalBriefingMonthDays, describeBriefingSchedule, isValidBriefingTimezone, nextBriefingScheduleDates, parseBriefingScheduleExpr, type BriefingScheduleFrequency, type BriefingScheduleMonthDay, type BriefingScheduleMonthInterval, type BriefingScheduleMonthlyOn, type BriefingScheduleOrdinal, type BriefingScheduleViewModel, } from './schedule.js';
-export { briefingAttachmentFormatLabel, briefingAttachmentNeedsExportJob, getBriefingCardAttachmentCapability, getBriefingCardAttachmentFormats, getDefaultBriefingCardAttachmentFormat, isBriefingTableExportCardType, type BriefingCardAttachmentCapability, } from './attachments.js';
+export { briefingAttachmentFileTraits, briefingAttachmentFormatLabel, briefingAttachmentNeedsExportJob, briefingAttachmentProduction, type BriefingAttachmentFileTraits, type BriefingAttachmentProduction, getBriefingCardAttachmentCapability, getBriefingCardAttachmentFormats, getDefaultBriefingCardAttachmentFormat, isBriefingTableExportCardType, type BriefingCardAttachmentCapability, } from './attachments.js';
 export { BRIEFING_ATTACHMENT_OMISSION_CODES, isBriefingAttachmentOmissionCode, readBriefingOmittedAttachments, type BriefingAttachmentOmissionCode, type BriefingOmittedAttachment, } from './attachment-outcomes.js';
 export { canCreateBriefingForUser, type BriefingUiUser } from './capabilities.js';
 export { getBriefingCreationIntents, type BriefingAuthorIntent, } from './creation.js';
@@ -167,8 +166,9 @@ export type BriefingContentDocument = {
     summary?: string;
     blocks: BriefingContentBlock[];
 };
-/** A rendered PDF, or a data file (CSV or Excel) made by an export. */
-export type BriefingAttachmentFormat = 'pdf' | ExportFileFormat;
+/** A rendered PDF or PNG image, or a data file (CSV or Excel, `ExportFileFormat`). */
+export declare const BRIEFING_ATTACHMENT_FORMATS: readonly ["pdf", "png", "csv", "xlsx"];
+export type BriefingAttachmentFormat = (typeof BRIEFING_ATTACHMENT_FORMATS)[number];
 export type BriefingPdfPageSize = 'letter' | 'legal' | 'a4' | 'a3' | 'tabloid';
 export type BriefingPdfOrientation = 'portrait' | 'landscape';
 export type BriefingCsvDelimiter = ',' | ';' | '\t';
@@ -222,7 +222,8 @@ export type BriefingAttachment = (BriefingAttachmentBase & {
     type: 'dashboard_sheet';
     dashboardId: string;
     sheetId: string;
-    format: 'pdf';
+    /** A sheet prints as a PDF or a PNG image of the whole sheet. */
+    format: 'pdf' | 'png';
 }) | (BriefingAttachmentBase & {
     type: 'document_sheet';
     dashboardId: string;

package/dist/types/components/surfboard/filter/types.d.ts

@@ -45,13 +45,6 @@ export type FixedDayDefaultDateFilter = {
     date: string;
 };
 export type DefaultDateFilter = RelativeDateFilter | FixedMonthDefaultDateFilter | FixedDayDefaultDateFilter;
-/**
- * Display mode for individual filters
- * - 'canvas': Filter displayed as a draggable card on the dashboard canvas
- * - 'toolbar': Filter displayed in the compact toolbar
- * - 'inherit': Use the dashboard's filterLayout.displayMode setting (default)
- */
-export type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 export type FilterKind = 'field' | 'global-date';
 /**
  * Target column configuration for multi-field filters.
@@ -133,13 +126,6 @@ export type TFilter = {
      * Defaults vary by filter type (160px for dropdowns, 220px for date ranges, etc.)
      */
     toolbarWidth?: number;
-    /**
-     * Display mode for this filter
-     * - 'canvas': Always show as draggable card on canvas
-     * - 'toolbar': Always show in toolbar
-     * - 'inherit': Use dashboard's filterLayout.displayMode setting (default)
-     */
-    displayMode?: FilterDisplayMode;
 };
 export type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
 type BaseFilter = {

package/dist/types/lib/dashboard-inputs/dashboard-filter-mapping-authoring.d.ts

@@ -1,7 +1,12 @@
 import { TFilter } from '../../components/surfboard/filter/types.js';
-import { DashboardInputScope, ReferencedFilterDashboardInput, TDashboard } from '../types/common-types.js';
-import { buildDashboardCardSourceIndex, DashboardFilterCardApplication, DashboardFilterOptionSource, DashboardFilterTarget, DashboardFilterTargetField } from '../../shared/dashboard-authoring/index.js';
-import { DashboardFilterOptionPolicy } from './dashboard-filter-mapping-storage-transition.js';
+import { DashboardInputScope, TCard, TDashboard } from '../types/common-types.js';
+import { DashboardFilterApplication, DashboardFilterCardApplication, DashboardFilterTarget, DashboardFilterTargetField } from '../../shared/dashboard-authoring/index.js';
+import { FilterRef, ReachedCard } from '../../shared/dashboard-authoring/filter-model/index.js';
+/**
+ * Filter mapping (one filter model M3, SPEC 4.4): the Cards tab of any filter
+ * input. `draftDashboardFilterMapping` builds the rows from the cards the
+ * input reaches and, with them, exactly what Accept would save. Pure.
+ */
 export type DashboardFilterMappingCandidateCatalog = {
     status: 'ready';
     targets: DashboardFilterTarget[];
@@ -18,7 +23,13 @@ export type DashboardFilterMappingDraftDecision = {
 export type DashboardFilterMappingDraftStatus = 'pendingSource' | 'automatic' | 'suggested' | 'needsMapping' | 'mapped' | 'notApplicable' | 'excluded' | 'invalidMapping' | 'metadataUnavailable';
 export type DashboardFilterMappingDraftRow = {
     cardId: string;
+    /** The panel reads the title and meta line from it. */
+    card: TCard;
     sheetId: string;
+    sheetKind: 'dashboard' | 'document';
+    sectionId?: string;
+    /** The section's title, for a card in a Document section. */
+    sectionTitle?: string;
     executionKind: 'config' | 'sql' | 'unconfigured';
     status: DashboardFilterMappingDraftStatus;
     candidates: DashboardFilterTarget[];
@@ -28,27 +39,28 @@ export type DashboardFilterMappingDraftRow = {
     guidanceMessage?: string;
     automaticFieldName?: string;
 };
-export type DashboardFilterMappingDraft = {
-    filterId: string;
-    existingInputId?: string;
-    outerScope: Extract<DashboardInputScope, {
-        kind: 'allSheets' | 'sheets';
-    }>;
+export type DashboardFilterMappingGroup = {
+    sheetId: string;
+    sheetTitle: string;
+    sheetKind: 'dashboard' | 'document';
     rows: DashboardFilterMappingDraftRow[];
 };
-export type DashboardFilterMappingAuthoringIssueCode = 'filterNotFound' | 'mappingNotFound' | 'globalDateUnsupported' | 'conflictingDashboardInput' | 'unsupportedOuterScope' | 'unsupportedRuntimeScope' | 'missingDecision' | 'invalidTarget' | 'metadataUnavailable';
-export type DashboardFilterMappingAuthoringIssue = {
-    code: DashboardFilterMappingAuthoringIssueCode;
+export type DashboardFilterMappingIssueCode = 'inputNotFound' | 'globalDateUnsupported' | 'unsupportedOuterScope' | 'unsupportedRuntimeScope' | 'missingDecision' | 'invalidTarget' | 'metadataUnavailable';
+export type DashboardFilterMappingIssue = {
+    code: DashboardFilterMappingIssueCode;
     message: string;
-    filterId: string;
+    ref: FilterRef;
+    /** Set once the ref resolved. */
+    inputId?: string;
     cardId?: string;
 };
-export type DashboardFilterMappingDraftResult = {
+/** What Accept would save, computed with the rows. */
+export type DashboardFilterMappingAcceptance = {
     ok: true;
-    draft: DashboardFilterMappingDraft;
+    application: DashboardFilterApplication;
 } | {
     ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    issues: DashboardFilterMappingIssue[];
 };
 export type DashboardFilterMappingStatusSummary = {
     coveredCount: number;
@@ -57,65 +69,58 @@ export type DashboardFilterMappingStatusSummary = {
     invalidCount: number;
     attentionCount: number;
 };
-/**
- * One presentation-neutral projection of authoritative Cards-tab rows.
- * Consumers must not independently reinterpret draft statuses when deciding
- * whether an author needs to act.
- */
-export declare function summarizeDashboardFilterMappingRows(rows: DashboardFilterMappingDraftRow[]): DashboardFilterMappingStatusSummary;
-export type DashboardFilterMappingAcceptanceResult = {
-    ok: true;
-    draft: DashboardFilterMappingDraft;
-    input: ReferencedFilterDashboardInput;
-} | {
-    ok: false;
-    draft?: DashboardFilterMappingDraft;
-    issues: DashboardFilterMappingAuthoringIssue[];
-};
-export type DashboardFilterMappingDisableResult = {
-    ok: true;
+export type DashboardFilterMappingDraft = {
     inputId: string;
-} | {
-    ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    filterId: string;
+    /** The scope the rows were computed with: the staged scope, else the saved one. Accept never changes it (S-5). */
+    scope: Exclude<DashboardInputScope, {
+        kind: 'documentSections';
+    }>;
+    /** The cards the rows were built for; the catalogs hook fetches metadata for exactly these. */
+    cards: readonly ReachedCard[];
+    /** One group per reached tab, in dashboard tab order; rows in `cards` order. */
+    groups: DashboardFilterMappingGroup[];
+    summary: DashboardFilterMappingStatusSummary;
+    acceptance: DashboardFilterMappingAcceptance;
 };
-export type DashboardFilterInputAcceptanceResult = {
+export type DashboardFilterMappingDraftResult = {
     ok: true;
-    input: ReferencedFilterDashboardInput;
-    created: boolean;
+    draft: DashboardFilterMappingDraft;
 } | {
     ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    issues: DashboardFilterMappingIssue[];
 };
-export type DashboardFilterMappingAuthoringRequest = {
-    filterId: string;
+export type DashboardFilterMappingRequest = {
+    /** The filter. Chips pass `{ inputId }`, a toolbar filter's compatibility id included. */
+    ref: FilterRef;
+    /** The dashboard as saved. */
+    dashboard: TDashboard;
+    /** The definition being edited, if changed. */
+    stagedDefinition?: TFilter;
+    /** The scope being edited, if changed; otherwise the saved scope, unnarrowed (OF-D8). */
+    stagedScope?: DashboardInputScope;
     candidatesByCardId: Record<string, DashboardFilterMappingCandidateCatalog | undefined>;
     /** Grounded field that supplies the current filter value. */
     selectionField?: Pick<DashboardFilterTargetField, 'name' | 'sourceField'> & Partial<Pick<DashboardFilterTargetField, 'source'>>;
     /**
-     * Strictly proven identities eligible for Auto. Physical datasets in a
-     * semantic domain may expose both physical and semantic identities. An
-     * explicit empty array is authoritative and must not fall back to a
-     * candidate-only selectionField source.
+     * Strictly proven identities eligible for Auto. An explicit empty array is
+     * authoritative and must not fall back to a candidate-only selectionField source.
      */
     automaticSelectionSources?: DashboardFilterTargetField['source'][];
     /** Datatype of the raw selection value, which may differ from the label. */
     selectionDataType?: string;
-    /**
-     * Re-check saved targets against selectionField after the author changes
-     * the raw Option Value identity. Explicit draft decisions still win.
-     */
+    /** Re-check saved targets after the option value field changed. */
     revalidatePersistedTargets?: boolean;
     decisionsByCardId?: Record<string, DashboardFilterMappingDraftDecision | undefined>;
-    /** Staged outer sheet scope. Omit when the author did not edit Scope. */
-    outerScope?: DashboardFilterMappingDraft['outerScope'];
-    /** Test seam; production callers use opaque random UUIDs. */
+    /** Test seam for new binding ids; production uses opaque random UUIDs. */
     createId?: () => string;
 };
-export declare function buildDashboardFilterMappingOuterScope(params: {
-    filter: Pick<TFilter, 'sheetId' | 'applyToSheetIds' | 'excludeSheetIds'>;
-    dashboard: Pick<TDashboard, 'sheets'>;
-}): DashboardFilterMappingDraft['outerScope'];
+/**
+ * One presentation-neutral projection of authoritative Cards-tab rows.
+ * Consumers must not independently reinterpret draft statuses when deciding
+ * whether an author needs to act.
+ */
+export declare function summarizeDashboardFilterMappingRows(rows: DashboardFilterMappingDraftRow[]): DashboardFilterMappingStatusSummary;
 /**
  * One Cards row for a source-qualified value field that is not a toolbar
  * filter, such as a field a click carries. It is the same decision chain the
@@ -124,8 +129,11 @@ export declare function buildDashboardFilterMappingOuterScope(params: {
  * authoring surface. Equality is the only operation a click applies.
  */
 export declare function buildDashboardFilterMappingDraftRowForValueField(params: {
-    card: Parameters<typeof buildDashboardCardSourceIndex>[0];
+    card: TCard;
     sheetId: string;
+    sheetKind: 'dashboard' | 'document';
+    sectionId?: string;
+    sectionTitle?: string;
     valueField: DashboardFilterTargetField;
     catalog: DashboardFilterMappingCandidateCatalog | undefined;
     decision?: DashboardFilterMappingDraftDecision;
@@ -133,27 +141,5 @@ export declare function buildDashboardFilterMappingDraftRowForValueField(params:
     /** Bindings already accepted elsewhere for this value field, offered as inherited matches. */
     acceptedTargets?: DashboardFilterTarget[];
 }): DashboardFilterMappingDraftRow;
-/** The reference-backed Input for a dashboard filter, mapped or not. */
-export declare function findReferencedDashboardFilterInput(dashboard: Pick<TDashboard, 'inputs'>, filterId: string): ReferencedFilterDashboardInput | undefined;
-export declare function acceptDashboardFilterInputDraft(params: {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets' | 'inputs'>;
-    updatedFilter: TFilter;
-    optionSource?: DashboardFilterOptionSource;
-    /** Option dependency policy to persist; omitted keeps the existing one. */
-    optionPolicy?: DashboardFilterOptionPolicy;
-    inputMetadata?: {
-        variableName?: string;
-        forceSelection?: boolean;
-    };
-    createId?: () => string;
-}): DashboardFilterInputAcceptanceResult;
-export declare function buildDashboardFilterMappingDraft(params: {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets' | 'inputs'>;
-    request: DashboardFilterMappingAuthoringRequest;
-}): DashboardFilterMappingDraftResult;
-export declare function acceptDashboardFilterMappingDraft(params: {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets' | 'inputs'>;
-    request: DashboardFilterMappingAuthoringRequest;
-    updatedFilter?: TFilter;
-}): DashboardFilterMappingAcceptanceResult;
-export declare function findMappedDashboardFilterInput(dashboard: Pick<TDashboard, 'inputs'>, filterId: string): ReferencedFilterDashboardInput | undefined;
+/** The one entry point of M3 (SPEC 4.4). Pure. */
+export declare function draftDashboardFilterMapping(request: DashboardFilterMappingRequest): DashboardFilterMappingDraftResult;

package/dist/types/lib/dashboard-inputs/dashboard-input-target-context.d.ts

@@ -108,12 +108,4 @@ export declare function createExplicitDashboardInputTargetContext(params: {
     controls?: DashboardInputTargetContext['controls'];
     target?: NormalizedFilterDashboardInput;
 }): DashboardInputTargetContext;
-/**
- * Applicability for option peers. A card-local or section-local target sees
- * exactly what applies to it. A sheet-level target additionally sees the
- * Inputs local to cards or sections on that sheet, the same rule the toolbar
- * uses to decide what a sheet presents, so option narrowing and presentation
- * agree on what "on this sheet" means.
- */
-export declare function doesDashboardInputApplyToTargetScope(input: Pick<NormalizedDashboardInput, 'scope' | 'compatibility'>, scope: DashboardInputTargetScope, sheetLocalCardIds: ReadonlySet<string>): boolean;
 export declare function describeInput(input: Pick<NormalizedDashboardInput, 'id' | 'label'> & Partial<Pick<NormalizedFilterDashboardInput, 'filter'>>): string;

package/dist/types/lib/dashboard-inputs/dashboard-input-values.d.ts

@@ -18,8 +18,27 @@ export declare function setDashboardInputRuntimeSlot(values: DashboardInputValue
  */
 export declare function materializeDashboardInputRuntimeSlot(input: NormalizedDashboardInput, slot: DashboardInputSlot | undefined): DashboardInputSlot | undefined;
 export declare function removeDashboardInputRuntimeSlot(values: DashboardInputValues, input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget): DashboardInputValues;
+/**
+ * Whether a filter input holds an active value on a tab, as its chip shows
+ * it: its slot for the tab, the saved default included. The one rule both
+ * filter bars (the toolbar and a Document's input bar) count and clear by
+ * for Clear all. It reads the slot directly, so a filter scoped to specific
+ * cards on the tab counts although it applies to no tab-level target.
+ */
+export declare function hasActiveFilterInputValueOnTab(params: {
+    dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>;
+    input: NormalizedDashboardInput;
+    runtimeValues?: DashboardInputValues;
+    sheetId: string | null | undefined;
+    calendar: CalendarContext | null;
+}): boolean;
 export declare function hydrateAuthoredDashboardInputSlot(params: {
-    dashboard: Pick<TDashboard, 'defaultInputValues'>;
+    /**
+     * Saved defaults come from the filter model (SPEC 5.2), so a toolbar
+     * filter's `defaultFilterValues` entry counts. A caller with only stored
+     * slot defaults may pass just those.
+     */
+    dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>;
     input: NormalizedDashboardInput;
     runtimeValues?: DashboardInputValues;
     target: DashboardInputRuntimeTarget;
@@ -46,3 +65,18 @@ export declare function createFilterDashboardInputSlot(filterValue: TFilterValue
 export declare function createControlDashboardInputSlot(value: unknown): DashboardInputSlot | undefined;
 export declare function cloneDashboardInputValues(values: DashboardInputValues | undefined): DashboardInputValues;
 export declare function compactDashboardInputValues(values: DashboardInputValues): DashboardInputValues;
+/**
+ * `over`'s slots win; a slot it does not have keeps `base`'s. A slot of `over`
+ * that holds only a comparison choice keeps `base`'s value under it, as the
+ * old filter value list and the comparison slot stayed apart. `base` itself
+ * when `over` is empty.
+ */
+export declare function overlayDashboardInputValues(base: DashboardInputValues, over: DashboardInputValues): DashboardInputValues;
+/** The values without any slot of these inputs, on every target. `values` itself when none is held. */
+export declare function removeDashboardInputSlotsById(values: DashboardInputValues, inputIds: ReadonlySet<string>): DashboardInputValues;
+/**
+ * The saved defaults the runtime reads (SPEC 5.2): the filter model's, which
+ * hold owned `defaultFilterValues` entries as slots. With no such entry they
+ * are the stored slots, read without building the model.
+ */
+export declare function savedDefaultInputValues(dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>): DashboardInputValues | undefined;

package/dist/types/lib/dashboard-inputs/filter-settings.d.ts

@@ -0,0 +1,199 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInput, DashboardInputScope, DashboardInputValues, EmbeddedFilterDashboardInput, TDashboard } from '../types/common-types.js';
+import { GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { DashboardFilterMappingContractIssue, DashboardFilterOptionDependencies, DashboardFilterOptionPopulation, DashboardFilterOptionSource } from '../../shared/dashboard-authoring/index.js';
+import { FilterRef } from '../../shared/dashboard-authoring/filter-model/index.js';
+import { DataSource, Field } from '../types/explorer-types.js';
+import { DashboardFilterMappingDraft, DashboardFilterMappingIssue } from './dashboard-filter-mapping-authoring.js';
+import { DashboardInputRuntimeTarget } from './dashboard-input-values.js';
+import { DefaultsCalendar } from '../utils/filter-default-value-utils.js';
+/**
+ * Filter settings (one filter model M4, SPEC 4.5): every settings write of a
+ * filter input, in one transaction. `applyFilterSettingsChange` is the pure
+ * core (the next dashboard, with saved defaults, and the runtime value
+ * effects); the store's `saveFilterSettings` applies both in one write with
+ * `applyFilterValueEffects`. Every filter is an input that holds its own
+ * definition (Phase 5), so there is one storage row: the input and its slots.
+ */
+/** Every authorable setting. `undefined` = unchanged; `null` = remove. */
+export type FilterSettingsChange = {
+    /** Column, title, operator, defaults, presentation fields. Reach fields in it are ignored. */
+    definition?: TFilter;
+    label?: string;
+    variableName?: string;
+    forceSelection?: boolean;
+    requiredAtExecution?: boolean;
+    scope?: DashboardInputScope;
+    optionSource?: DashboardFilterOptionSource | null;
+    optionDependencies?: DashboardFilterOptionDependencies | null;
+    optionPopulation?: DashboardFilterOptionPopulation | null;
+    /** Save a draft's acceptance, or remove the mapping. */
+    mapping?: {
+        kind: 'save';
+        draft: DashboardFilterMappingDraft;
+    } | {
+        kind: 'remove';
+    };
+    /** Value effects the author asked for, at one runtime target. */
+    values?: {
+        /** The default this target loads changed; its runtime slot resets to the default. */
+        defaultChanged?: boolean;
+        /** Global Date and date filters: the saved comparison selection (`null` removes it). */
+        defaultComparisonSelection?: GlobalDateComparisonSelection | null;
+        /** The option value field changed; stored selections no longer mean the same values. */
+        selectionIdentityChanged?: boolean;
+        target: DashboardInputRuntimeTarget;
+    };
+};
+export type FilterSettingsIssue = DashboardFilterMappingIssue | {
+    code: 'invalidSettings';
+    message: string;
+    ref: FilterRef;
+    inputId?: string;
+    contractIssue?: DashboardFilterMappingContractIssue;
+};
+export type FilterValueEffect = {
+    kind: 'resetToDefault';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+    filterValue?: TFilterValue;
+} | {
+    kind: 'clear';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+} | {
+    kind: 'setDefaultComparison';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+}
+/** A scope change: drop the live slot of a target the input no longer reaches. */
+ | {
+    kind: 'dropTargetSlot';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+};
+export type FilterSettingsChangeResult = {
+    ok: true;
+    dashboard: TDashboard;
+    inputId: string;
+    valueEffects: FilterValueEffect[];
+} | {
+    ok: false;
+    issues: FilterSettingsIssue[];
+};
+export type FilterSettingsSaveResult = {
+    ok: true;
+    inputId: string;
+} | {
+    ok: false;
+    issues: FilterSettingsIssue[];
+};
+export type FilterSettingsContext = {
+    /** The report calendar defaults resolve in; null only before the report context loads. */
+    calendar: CalendarContext | null;
+};
+/** The effective forceSelection for a filter (moved unchanged from the authoring policy). */
+export declare function resolveFilterInputForceSelection(requested: boolean | undefined, filter: TFilter | undefined, timezone?: string): true | undefined;
+/**
+ * A new filter from a catalog field (SPEC 4.5): one shared value for every
+ * target it reaches (OF-D18), its placement derived from the definition
+ * (S-7), and a variable name unique against the existing inputs.
+ */
+export declare function buildFilterInputFromField(params: {
+    field: Field;
+    dataSource?: DataSource | null;
+    connectionId?: string;
+    connectionType?: string;
+    scope: DashboardInputScope;
+    existingInputs: readonly DashboardInput[];
+    createId?: () => string;
+}): EmbeddedFilterDashboardInput;
+/**
+ * A new filter input holding this definition (one filter model Phase 5):
+ * every new filter, from a catalog field or the toolbar's field picker, or
+ * the Global Date. One shared value for every target it reaches (OF-D18), its
+ * placement derived from the definition (S-7), a variable name unique against
+ * the existing inputs, and no reach fields (reach is the scope).
+ */
+export declare function buildFilterInputFromDefinition(params: {
+    filter: TFilter;
+    label?: string;
+    scope: DashboardInputScope;
+    existingInputs: readonly DashboardInput[];
+    createId?: () => string;
+}): EmbeddedFilterDashboardInput;
+/** The pure core (SPEC 4.5). Never partially applies. */
+export declare function applyFilterSettingsChange(dashboard: TDashboard, ref: FilterRef, change: FilterSettingsChange, context?: FilterSettingsContext): FilterSettingsChangeResult;
+/**
+ * Applies the core's value effects to the store's input values, in the same
+ * write as the dashboard (SPEC 4.5 rule 4). `before` is the dashboard the
+ * change was made on.
+ */
+export declare function applyFilterValueEffects(params: {
+    dashboardInputValues: DashboardInputValues;
+    effects: readonly FilterValueEffect[];
+    before: TDashboard;
+    after: TDashboard;
+    calendar: CalendarContext | null;
+}): DashboardInputValues;
+export type DashboardFilterStorageState = {
+    dashboardInputValues: DashboardInputValues;
+    defaultInputValues?: DashboardInputValues;
+};
+export type DashboardFilterAuthoringSettingsUpdate = {
+    forceSelection?: boolean;
+    /**
+     * The caller changed the default its target loads. Filter settings start
+     * from the target's saved default (`resolveAuthoredFilterDefaultFields`),
+     * which can differ from the definition for a scoped Input or an overlay
+     * entry, so they say so; callers that start from the definition leave it
+     * unset and the owner compares definitions. Also resets a saved slot that
+     * has no backing default.
+     */
+    defaultValueChanged?: boolean;
+    defaultComparisonChanged?: boolean;
+    defaultComparisonSelection?: GlobalDateComparisonSelection;
+    target?: DashboardInputRuntimeTarget;
+    optionSourceChanged?: boolean;
+    optionSource?: DashboardFilterOptionSource;
+    /** Authored option dependency policy edit; undefined value restores the
+     * dashboard default (omitted, meaning All applicable). */
+    optionDependenciesChanged?: boolean;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulationChanged?: boolean;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    /** Raw selection identity changed; the previous runtime value is invalid. */
+    selectionIdentityChanged?: boolean;
+};
+/**
+ * Callers submit edits; the owner decides whether defaults must be reseeded.
+ * A default change (values, date window or mode) writes the target's saved
+ * default and live value; the definition, which the caller submits whole,
+ * holds the last authored default.
+ */
+export declare function resolveFilterAuthoringSettings(previous: TFilter | undefined, filter: TFilter, settings: DashboardFilterAuthoringSettingsUpdate | undefined, target: DashboardInputRuntimeTarget, calendar?: DefaultsCalendar): {
+    target: DashboardInputRuntimeTarget;
+    defaultValueChanged: boolean;
+    defaultFilterValue: TFilterValue | undefined;
+    forceSelection?: boolean;
+    defaultComparisonChanged?: boolean;
+    defaultComparisonSelection?: GlobalDateComparisonSelection;
+    optionSourceChanged?: boolean;
+    optionSource?: DashboardFilterOptionSource;
+    optionDependenciesChanged?: boolean;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulationChanged?: boolean;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    selectionIdentityChanged?: boolean;
+};
+/**
+ * Applies Basic-tab default edits to the same storage transaction that changes
+ * mapped participation. This keeps the authoritative filter, mapped input, and
+ * its runtime/default slots from becoming observable in mixed states.
+ */
+export declare function applyFilterAuthoringSettingsToStorage(params: {
+    state: DashboardFilterStorageState;
+    input: Pick<DashboardInput, 'id' | 'runtimeScope'>;
+    settings?: ReturnType<typeof resolveFilterAuthoringSettings>;
+}): DashboardFilterStorageState;

package/dist/types/lib/dashboard-inputs/resolve-dashboard-input-context.d.ts

@@ -3,12 +3,17 @@ import { CardViewStateMap } from '../dashboard-view-state/index.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { DashboardInputValues, NormalizedDashboardInput, ResolvedDashboardInput, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
 import { DashboardInputRuntimeTarget } from './dashboard-input-values.js';
-import { doesDashboardInputApplyToTarget } from './dashboard-input-scope.js';
+import { doesDashboardInputApplyToTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
 import { TransientInputContext } from './transient-input-context.js';
 export { doesDashboardInputApplyToTarget };
 export type DashboardInputRuntimeValues = {
     dashboardInputValues?: DashboardInputValues;
-    filterValues?: TFilterValue[];
+    /**
+     * Runtime-only values no filter defines (chart clicks, summary chips; one
+     * filter model SPEC 5.8). Input resolution never reads them; authored filter
+     * values are slots.
+     */
+    adHocFilterValues?: TFilterValue[];
     controlValues?: Record<string, unknown>;
     inlineFilterValuesMap?: Record<string, TFilterValue[] | undefined>;
     cardControlValuesMap?: Record<string, Record<string, unknown>>;

package/dist/types/lib/dashboard-inputs/resolve-selection-input.d.ts

@@ -1,6 +1,6 @@
 import { SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
 import { DashboardFilterTarget } from '../../shared/dashboard-authoring/index.js';
-import { ScopedDashboardInputTarget } from './dashboard-input-scope.js';
+import { ScopedDashboardInputTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
 import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../types/common-types.js';
 import { FilterCondition } from '../types/explorer-types.js';
 export type SelectionSkipReason =