@dereekb/dbx-form 13.4.0 → 13.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-form",
-  "version": "13.4.0",
+  "version": "13.4.2",
   "peerDependencies": {
     "@angular/cdk": "^21.0.0",
     "@angular/common": "^21.0.0",
@@ -10,12 +10,12 @@
     "@angular/material-date-fns-adapter": "^21.0.0",
     "@angular/platform-browser": "^21.0.0",
     "@bobbyquantum/ngx-editor": "21.0.0-beta.1",
-    "@dereekb/date": "13.4.0",
-    "@dereekb/dbx-core": "13.4.0",
-    "@dereekb/dbx-web": "13.4.0",
-    "@dereekb/model": "13.4.0",
-    "@dereekb/rxjs": "13.4.0",
-    "@dereekb/util": "13.4.0",
+    "@dereekb/date": "13.4.2",
+    "@dereekb/dbx-core": "13.4.2",
+    "@dereekb/dbx-web": "13.4.2",
+    "@dereekb/model": "13.4.2",
+    "@dereekb/rxjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
     "@ng-web-apis/geolocation": "^5.1.0",
     "@ngbracket/ngx-layout": "^21.0.0",
     "@ngrx/component-store": "^21.0.0",

package/types/dereekb-dbx-form-calendar.d.ts

@@ -184,10 +184,40 @@ interface CalendarScheduleSelectionState extends PartialCalendarScheduleSelectio
      */
     readonly initialSelectionState?: Maybe<AllOrNoneSelection>;
 }
+/**
+ * Creates the default initial state for the calendar schedule selection store,
+ * using the current system timezone and all days of the week enabled.
+ *
+ * @returns A fresh CalendarScheduleSelectionState with default values
+ */
 declare function initialCalendarScheduleSelectionState(): CalendarScheduleSelectionState;
+/**
+ * Computes the effective min and max date range by combining the filter and the explicit minMaxDateRange constraints.
+ *
+ * @param x - State containing filter and minMaxDateRange to compute from
+ * @returns A partial date range with the effective start and end boundaries
+ */
 declare function calendarScheduleMinAndMaxDateRange(x: Pick<CalendarScheduleSelectionState, 'filter' | 'minMaxDateRange'>): Partial<DateRange>;
+/**
+ * Returns the effective minimum date by taking the latest start date between the filter and minMaxDateRange.
+ *
+ * @param x - State containing filter and minMaxDateRange
+ * @returns The latest start date, or undefined if none
+ */
 declare function calendarScheduleMinDate(x: Pick<CalendarScheduleSelectionState, 'filter' | 'minMaxDateRange'>): Maybe<Date>;
+/**
+ * Returns the effective maximum date by taking the earliest end date between the filter and minMaxDateRange.
+ *
+ * @param x - State containing filter and minMaxDateRange
+ * @returns The earliest end date, or undefined if none
+ */
 declare function calendarScheduleMaxDate(x: Pick<CalendarScheduleSelectionState, 'filter' | 'minMaxDateRange'>): Maybe<Date>;
+/**
+ * Returns whether the filter's start date is being used as the effective start for the selection result computation.
+ *
+ * @param x - State containing filter and computeSelectionResultRelativeToFilter
+ * @returns True if the filter start is being used for the selection result
+ */
 declare function calendarScheduleStartBeingUsedFromFilter(x: Pick<CalendarScheduleSelectionState, 'filter' | 'computeSelectionResultRelativeToFilter'>): boolean | _dereekb_util.MaybeNot;
 declare class DbxCalendarScheduleSelectionStore extends ComponentStore<CalendarScheduleSelectionState> {
     constructor();
@@ -282,16 +312,103 @@ declare class DbxCalendarScheduleSelectionStore extends ComponentStore<CalendarS
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DbxCalendarScheduleSelectionStore, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<DbxCalendarScheduleSelectionStore>;
 }
+/**
+ * Updates the state with an initial selection (all or none) and applies it when no dates are currently toggled.
+ *
+ * @param state - The current selection state
+ * @param initialSelectionState - The initial selection mode ('all' or 'none')
+ * @returns The updated selection state
+ */
 declare function updateStateWithInitialSelectionState(state: CalendarScheduleSelectionState, initialSelectionState: Maybe<AllOrNoneSelection>): CalendarScheduleSelectionState;
+/**
+ * Updates the computeSelectionResultRelativeToFilter flag and recalculates the state if the value changed.
+ *
+ * @param currentState - The current selection state
+ * @param computeSelectionResultRelativeToFilter - Whether to compute results relative to the filter
+ * @returns The updated selection state
+ */
 declare function updateStateWithComputeSelectionResultRelativeToFilter(currentState: CalendarScheduleSelectionState, computeSelectionResultRelativeToFilter: Maybe<boolean>): CalendarScheduleSelectionState;
+/**
+ * Updates the state with date exclusions, converting input dates/ranges to cell indexes and reapplying the filter.
+ *
+ * @param state - The current selection state
+ * @param inputExclusions - Dates, date ranges, or cell indexes to exclude
+ * @returns The updated selection state with exclusions applied
+ */
 declare function updateStateWithExclusions(state: CalendarScheduleSelectionState, inputExclusions: Maybe<ArrayOrValue<DateOrDateRangeOrDateCellIndexOrDateCellRange>>): CalendarScheduleSelectionState;
+/**
+ * Sets the min/max date range constraint on the state, normalizing start to startOfDay and end to endOfDay.
+ *
+ * @param state - The current selection state
+ * @param minMaxDateRange - The min/max boundary dates to enforce
+ * @returns The updated selection state with the boundary applied
+ */
 declare function updateStateWithMinMaxDateRange(state: CalendarScheduleSelectionState, minMaxDateRange: Maybe<Partial<DateRange>>): CalendarScheduleSelectionState;
+/**
+ * Applies a date cell schedule filter to the selection state, computing the enabled day function
+ * from the filter, exclusions, and min/max date range constraints.
+ *
+ * @param currentState - The current selection state
+ * @param inputFilter - The filter configuration to apply
+ * @returns The updated selection state with the filter applied
+ */
+/**
+ * Applies a date cell schedule filter to the selection state, computing the enabled day function
+ * from the filter, exclusions, and min/max date range constraints.
+ *
+ * @param currentState - The current selection state
+ * @param inputFilter - The filter configuration to apply
+ * @returns The updated selection state with the filter applied
+ */
 declare function updateStateWithFilter(currentState: CalendarScheduleSelectionState, inputFilter: Maybe<DateCellScheduleDateFilterConfig>): CalendarScheduleSelectionState;
+/**
+ * Updates the output timezone and transforms the current selection value to reflect the new timezone.
+ *
+ * @param state - The current selection state
+ * @param timezone - The target timezone string
+ * @returns The updated selection state with timezone-adjusted values
+ */
 declare function updateStateWithTimezoneValue(state: CalendarScheduleSelectionState, timezone: Maybe<TimezoneString>): CalendarScheduleSelectionState;
+/**
+ * Updates the state from an external date cell schedule range value, converting timezone-aware inputs
+ * to system time and synchronizing the internal selection indexes.
+ *
+ * @param state - The current selection state
+ * @param inputChange - The date cell schedule range to apply
+ * @returns The updated selection state
+ */
 declare function updateStateWithDateCellScheduleRangeValue(state: CalendarScheduleSelectionState, inputChange: Maybe<FullDateCellScheduleRangeInputDateRange>): CalendarScheduleSelectionState;
+/**
+ * Updates the default schedule day codes (used when no explicit schedule days are set) and recalculates allowed days.
+ *
+ * @param state - The current selection state
+ * @param change - The new default schedule day codes
+ * @returns The updated selection state
+ */
 declare function updateStateWithChangedDefaultScheduleDays(state: CalendarScheduleSelectionState, change: Maybe<Iterable<DateCellScheduleDayCode>>): CalendarScheduleSelectionState;
+/**
+ * Updates the explicit schedule day codes override and recalculates allowed days of the week.
+ *
+ * @param state - The current selection state
+ * @param change - The new schedule day codes, or null/undefined to clear the override
+ * @returns The updated selection state
+ */
 declare function updateStateWithChangedScheduleDays(state: CalendarScheduleSelectionState, change: Maybe<Iterable<DateCellScheduleDayCode>>): CalendarScheduleSelectionState;
+/**
+ * Switches between single and multiple selection mode, trimming the selection to a single value when switching to single mode.
+ *
+ * @param state - The current selection state
+ * @param selectionMode - The new selection mode
+ * @returns The updated selection state
+ */
 declare function updateStateWithSelectionMode(state: CalendarScheduleSelectionState, selectionMode: DbxCalendarScheduleSelectionStoreSelectionMode): CalendarScheduleSelectionState;
+/**
+ * Finalizes a schedule days change by recalculating allowed days of the week and updating toggled indexes accordingly.
+ *
+ * @param previousState - The state before the schedule days change
+ * @param nextState - The state with updated schedule day codes
+ * @returns The finalized selection state with recalculated allowed days and toggled indexes
+ */
 declare function finalizeUpdateStateWithChangedScheduleDays(previousState: CalendarScheduleSelectionState, nextState: CalendarScheduleSelectionState): CalendarScheduleSelectionState;
 interface CalendarScheduleSelectionStateDatesChange {
     reset?: true;
@@ -307,11 +424,59 @@ interface CalendarScheduleSelectionStateDatesChange {
      */
     invertSetBehavior?: boolean;
 }
+/**
+ * Applies date changes (toggle, add, remove, set, selectAll, or reset) to the calendar selection state,
+ * updating toggled indexes and input start/end accordingly.
+ *
+ * @param state - The current selection state
+ * @param change - The date changes to apply
+ * @returns The updated selection state
+ */
+/**
+ * Applies date changes (toggle, add, remove, set, selectAll, or reset) to the calendar selection state,
+ * updating toggled indexes and input start/end accordingly.
+ *
+ * @param state - The current selection state
+ * @param change - The date changes to apply
+ * @returns The updated selection state
+ */
 declare function updateStateWithChangedDates(state: CalendarScheduleSelectionState, change: CalendarScheduleSelectionStateDatesChange): CalendarScheduleSelectionState;
+/**
+ * Clears all date selections from the state, retaining other configuration like schedule days and filter.
+ *
+ * @param state - The current selection state
+ * @returns The state with all selections cleared
+ */
 declare function noSelectionCalendarScheduleSelectionState(state: CalendarScheduleSelectionState): CalendarScheduleSelectionState;
+/**
+ * Updates the selection state with a new start/end date range, retaining toggled indexes within the new range bounds.
+ *
+ * @param state - The current selection state
+ * @param change - The new input start and end dates
+ * @returns The updated selection state
+ */
 declare function updateStateWithChangedRange(state: CalendarScheduleSelectionState, change: CalendarScheduleSelectionInputDateRange): CalendarScheduleSelectionState;
+/**
+ * Finalizes a partially-built state by recomputing the isEnabledDay function and the current selection value.
+ *
+ * @param nextState - The partially-built selection state to finalize
+ * @returns The finalized selection state
+ */
 declare function finalizeNewCalendarScheduleSelectionState(nextState: Building<CalendarScheduleSelectionState>): CalendarScheduleSelectionState;
+/**
+ * Builds a decision function that determines whether a given day index is enabled (selected) in the current state.
+ *
+ * @param state - The selection state to derive the enabled-day function from
+ * @returns A function that returns true if the given day is enabled/selected
+ */
 declare function isEnabledDayInCalendarScheduleSelectionState(state: CalendarScheduleSelectionState): DecisionFunction<DateCellTimingRelativeIndexFactoryInput>;
+/**
+ * Computes the output DateCellScheduleDateRange value from the current selection state,
+ * applying timezone offsets and filter-relative computations as needed.
+ *
+ * @param state - The current selection state to compute from
+ * @returns The computed selection value, or null if nothing is selected
+ */
 declare function computeScheduleSelectionValue(state: CalendarScheduleSelectionState): Maybe<CalendarScheduleSelectionValue>;
 /**
  * The selected date range and the corresponding cell range.
@@ -326,8 +491,27 @@ interface CalendarScheduleSelectionRangeAndExclusion extends DateRange {
      */
     excluded: DateCellIndex[];
 }
+/**
+ * Computes the selected date range with its corresponding cell range and all excluded day indexes.
+ * Returns null if no days are selected.
+ *
+ * @param state - The current selection state
+ * @returns The range and exclusion data, or null if nothing is selected
+ */
 declare function computeScheduleSelectionRangeAndExclusion(state: CalendarScheduleSelectionState): Maybe<CalendarScheduleSelectionRangeAndExclusion>;
+/**
+ * Computes the selected date range (start and end dates) from the current selection state.
+ *
+ * @param state - The current selection state
+ * @returns The selected date range, or undefined if nothing is selected
+ */
 declare function computeCalendarScheduleSelectionRange(state: CalendarScheduleSelectionState): Maybe<DateRange>;
+/**
+ * Computes the date cell index range (i, to) that spans all selected and toggled days in the current state.
+ *
+ * @param state - The current selection state
+ * @returns The cell range spanning all selected days, or undefined if nothing is selected
+ */
 declare function computeCalendarScheduleSelectionDateCellRange(state: CalendarScheduleSelectionState): Maybe<DateCellRangeWithRange>;
 
 /**
@@ -442,6 +626,12 @@ declare class DbxFormCalendarDateScheduleRangeFieldComponent<T extends DbxFormCa
 
 interface DateScheduleRangeFieldConfig extends Omit<LabeledFieldConfig, 'key' | 'placeholder'>, DescriptionFieldConfig, Partial<FieldConfig>, DbxFormCalendarDateCellScheduleRangeFieldProps {
 }
+/**
+ * Creates a Formly field configuration for a date schedule range picker with calendar-based selection.
+ *
+ * @param config - Optional schedule range field configuration overrides
+ * @returns A validated Formly field configuration for date schedule range selection
+ */
 declare function dateScheduleRangeField(config?: DateScheduleRangeFieldConfig): FormlyFieldConfig;
 
 declare class DbxFormDateScheduleRangeFieldModule {
@@ -479,6 +669,13 @@ interface DbxScheduleSelectionCalendarComponentConfig {
 type DbxScheduleSelectionCalendarBeforeMonthViewRenderModifyDayFunction = (viewDay: CalendarMonthViewDay<CalendarScheduleSelectionMetadata>, state: CalendarScheduleSelectionState) => void;
 type DbxScheduleSelectionCalendarBeforeMonthViewRenderFunction = (renderEvent: CalendarMonthViewBeforeRenderEvent) => void;
 type DbxScheduleSelectionCalendarBeforeMonthViewRenderFunctionFactory = (state: Observable<CalendarScheduleSelectionState>) => DbxScheduleSelectionCalendarBeforeMonthViewRenderFunction;
+/**
+ * Creates a factory that produces a beforeMonthViewRender handler for the schedule selection calendar.
+ * The handler applies CSS classes and metadata to each day cell based on the current selection state.
+ *
+ * @param inputModifyFn - Optional function to further customize each day cell after default processing
+ * @returns A factory function that accepts a state observable and produces a render handler
+ */
 declare function dbxScheduleSelectionCalendarBeforeMonthViewRenderFactory(inputModifyFn?: Maybe<DbxScheduleSelectionCalendarBeforeMonthViewRenderModifyDayFunction>): DbxScheduleSelectionCalendarBeforeMonthViewRenderFunctionFactory;
 declare class DbxScheduleSelectionCalendarComponent<T> implements OnInit, OnDestroy {
     readonly calendarStore: DbxCalendarStore<T>;
@@ -670,7 +867,18 @@ declare class DbxFormCalendarModule {
     static ɵinj: _angular_core.ɵɵInjectorDeclaration<DbxFormCalendarModule>;
 }
 
+/**
+ * Creates form fields for selecting which days of the week are enabled in a schedule selection calendar,
+ * wrapped in a responsive flex layout.
+ *
+ * @returns An array of Formly field configs with toggle fields for each day of the week
+ */
 declare function dbxScheduleSelectionCalendarDateDaysFormFields(): _ngx_formly_core.FormlyFieldConfig<i13.DbxFlexWrapperConfig>[];
+/**
+ * Creates an array of toggle field configs, one for each day of the week, keyed by lowercase day name.
+ *
+ * @returns An array of toggle Formly field configs for each day of the week
+ */
 declare function dbxScheduleSelectionCalendarDateDaysFormDayFields(): _ngx_formly_core.FormlyFieldConfig<_ngx_formly_core.FormlyFieldProps & {
     [additionalProperties: string]: any;
 }>[];

package/types/dereekb-dbx-form-mapbox.d.ts

@@ -120,6 +120,12 @@ declare class DbxFormMapboxLatLngFieldComponent<T extends DbxFormMapboxLatLngCom
 
 interface MapboxLatLngFieldConfig extends Omit<LabeledFieldConfig, 'key'>, DescriptionFieldConfig, Partial<FieldConfig>, Pick<DbxFormMapboxLatLngComponentFieldProps, 'showMap' | 'zoom' | 'latLngConfig' | 'recenterTime' | 'setCenterOnLocationSet' | 'showCenterButton' | 'selectLocationOnMapDrag' | 'selectLocationOnMapClick' | 'markerConfig'> {
 }
+/**
+ * Creates a Formly field configuration for a Mapbox-powered latitude/longitude picker with optional map display.
+ *
+ * @param config - Optional field configuration overrides
+ * @returns A validated Formly field configuration for the Mapbox lat/lng picker
+ */
 declare function mapboxLatLngField(config?: MapboxLatLngFieldConfig): FormlyFieldConfig;
 
 declare class DbxFormMapboxLatLngFieldMarkerComponent {
@@ -198,6 +204,12 @@ declare class DbxFormMapboxZoomFieldComponent<T extends DbxFormMapboxZoomCompone
 
 interface MapboxZoomFieldConfig extends Omit<LabeledFieldConfig, 'key'>, DescriptionFieldConfig, Partial<FieldConfig>, Pick<DbxFormMapboxZoomComponentFieldProps, 'showMap' | 'center' | 'minZoom' | 'maxZoom' | 'zoomStep'> {
 }
+/**
+ * Creates a Formly field configuration for a Mapbox-powered zoom level picker with optional map preview.
+ *
+ * @param config - Optional field configuration overrides
+ * @returns A validated Formly field configuration for the Mapbox zoom picker
+ */
 declare function mapboxZoomField(config?: MapboxZoomFieldConfig): FormlyFieldConfig;
 
 declare class DbxFormMapboxZoomModule {

package/types/dereekb-dbx-form-quiz.d.ts

@@ -216,6 +216,9 @@ declare class QuizStore extends ComponentStore<QuizStoreState> {
     /**
      * Returns a reactive observable of the answer for a given question, looked up by id, index, or the current question.
      *
+     * @param lookupInput - Lookup criteria specifying which question's answer to retrieve
+     * @returns An observable that emits the current answer for the specified question, or undefined if not answered
+     *
      * @example
      * ```ts
      * // By current question:
@@ -223,6 +226,8 @@ declare class QuizStore extends ComponentStore<QuizStoreState> {
      * // By question id:
      * store.answerForQuestion({ id: 'q1' }).subscribe(answer => console.log(answer));
      * ```
+     *
+     * @param lookupInput - Lookup criteria specifying which question's answer to retrieve
      */
     answerForQuestion(lookupInput: ObservableOrValue<QuizStoreAnswerLookupInput>): Observable<Maybe<QuizAnswer>>;
     readonly startQuiz: () => void;
@@ -281,6 +286,8 @@ declare abstract class QuizQuestionAccessor<T = unknown> {
 /**
  * Provides QuizQuestionAccessor bound to the current question in QuizStore.
  *
+ * @returns An Angular provider that binds QuizQuestionAccessor to the current quiz question
+ *
  * @usage
  * ```typescript
  * @Component({
@@ -643,21 +650,31 @@ declare class DbxQuizScoreComponent {
 /**
  * Creates a Likert scale question config with agreement prompt (Strongly Disagree to Strongly Agree).
  *
+ * @param text - The statement to rate agreement on
+ * @returns A quiz question config with an agreement-based prompt and guidance text
+ *
  * @example
  * ```ts
  * instance.config.set(quizAgreementPrompt('I feel confident leading under pressure.'));
  * // { prompt: 'Please rate how much you agree...', text: '...', guidance: '1 = Strongly Disagree, 5 = Strongly Agree' }
  * ```
+ *
+ * @param text - The statement to rate agreement on
  */
 declare function quizAgreementPrompt(text: string): QuizQuestionTextComponentConfig;
 /**
  * Creates a Likert scale question config with frequency prompt (Never to Always).
  *
+ * @param text - The statement to rate frequency on
+ * @returns A quiz question config with a frequency-based prompt and guidance text
+ *
  * @example
  * ```ts
  * instance.config.set(quizFrequencyPrompt('I break vague direction into first steps.'));
  * // { prompt: 'Please rate how much you agree...', text: '...', guidance: '1 = Never, 5 = Always' }
  * ```
+ *
+ * @param text - The statement to rate frequency on
  */
 declare function quizFrequencyPrompt(text: string): QuizQuestionTextComponentConfig;