@brightlocal/ui-components 2.18.0 → 2.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -28,10 +28,12 @@ type StepperItemState = "active" | "completed" | "inactive" | "error";
28
28
  /**
29
29
  * A single step descriptor. Consumers may attach any extra fields they need
30
30
  * (e.g. `title`, `href`); only `id` is required for ordering and state.
31
+ * Generic over the step-id type for type-safe `id` values.
32
+ * @typeParam TStepId - The type of step ids, defaults to `string`
31
33
  */
32
- interface StepperStep {
34
+ interface StepperStep<TStepId extends string = string> {
33
35
  /** Stable, unique identifier for the step. */
34
- id: string;
36
+ id: TStepId;
35
37
  [key: string]: unknown;
36
38
  }
37
39
 
@@ -97,21 +99,24 @@ function useStepperItem(): StepperItemContextValue {
97
99
 
98
100
  /**
99
101
  * Props for the Stepper root component.
102
+ * Generic over the step-id type for type-safe `value`, `steps[].id` and
103
+ * `onValueChange`.
104
+ * @typeParam TStepId - The type of step ids, defaults to `string`
100
105
  */
101
- interface StepperProps extends Omit<
106
+ interface StepperProps<TStepId extends string = string> extends Omit<
102
107
  React.ComponentPropsWithoutRef<"div">,
103
108
  "onChange"
104
109
  > {
105
110
  /** Data hook for automated testing (required). */
106
111
  dataHook: string;
107
112
  /** Ordered list of steps. Defines step order, total count and id → index resolution. */
108
- steps: StepperStep[];
113
+ steps: StepperStep<TStepId>[];
109
114
  /** Controlled active step id. */
110
- value?: string;
115
+ value?: TStepId;
111
116
  /** Active step id for uncontrolled usage. Defaults to the first step. */
112
- defaultValue?: string;
117
+ defaultValue?: TStepId;
113
118
  /** Called with the new active step id when the active step changes. */
114
- onValueChange?: (id: string) => void;
119
+ onValueChange?: (id: TStepId) => void;
115
120
  /**
116
121
  * Layout orientation.
117
122
  * @default "horizontal"
@@ -138,82 +143,90 @@ interface StepperProps extends Omit<
138
143
  * Tracks the active step (controlled or uncontrolled) and shares it with its
139
144
  * sub-components via context.
140
145
  */
141
- const Stepper = React.forwardRef<HTMLDivElement, StepperProps>(
142
- (
143
- {
144
- className,
145
- dataHook,
146
- steps,
147
- value,
148
- defaultValue,
149
- onValueChange,
150
- orientation = "horizontal",
151
- labelPlacement = "below",
152
- ariaLabel,
153
- trackingEl,
154
- trackingLabel,
155
- ...props
146
+ function StepperInner<TStepId extends string = string>(
147
+ {
148
+ className,
149
+ dataHook,
150
+ steps,
151
+ value,
152
+ defaultValue,
153
+ onValueChange,
154
+ orientation = "horizontal",
155
+ labelPlacement = "below",
156
+ ariaLabel,
157
+ trackingEl,
158
+ trackingLabel,
159
+ ...props
160
+ }: StepperProps<TStepId>,
161
+ ref: React.ForwardedRef<HTMLDivElement>
162
+ ) {
163
+ // Single layout token drives the orientation/placement-specific styles in
164
+ // the sub-components (CSS group-data selectors can't AND two attributes).
165
+ const layout =
166
+ orientation === "vertical"
167
+ ? "vertical"
168
+ : labelPlacement === "inline"
169
+ ? "horizontal-inline"
170
+ : "horizontal-below";
171
+ const isControlled = value !== undefined;
172
+ const [internalId, setInternalId] = React.useState<string>(
173
+ defaultValue ?? steps[0]?.id ?? ""
174
+ );
175
+ const activeId = isControlled ? value : internalId;
176
+ const activeIndex = steps.findIndex((step) => step.id === activeId);
177
+
178
+ const setActiveStep = React.useCallback(
179
+ (id: string) => {
180
+ if (!isControlled) {
181
+ setInternalId(id);
182
+ }
183
+ onValueChange?.(id as TStepId);
156
184
  },
157
- ref
158
- ) => {
159
- // Single layout token drives the orientation/placement-specific styles in
160
- // the sub-components (CSS group-data selectors can't AND two attributes).
161
- const layout =
162
- orientation === "vertical"
163
- ? "vertical"
164
- : labelPlacement === "inline"
165
- ? "horizontal-inline"
166
- : "horizontal-below";
167
- const isControlled = value !== undefined;
168
- const [internalId, setInternalId] = React.useState(
169
- defaultValue ?? steps[0]?.id ?? ""
170
- );
171
- const activeId = isControlled ? value : internalId;
172
- const activeIndex = steps.findIndex((step) => step.id === activeId);
173
-
174
- const setActiveStep = React.useCallback(
175
- (id: string) => {
176
- if (!isControlled) {
177
- setInternalId(id);
178
- }
179
- onValueChange?.(id);
180
- },
181
- [isControlled, onValueChange]
182
- );
185
+ [isControlled, onValueChange]
186
+ );
183
187
 
184
- const contextValue = React.useMemo<StepperContextValue>(
185
- () => ({
186
- activeId,
187
- activeIndex,
188
- setActiveStep,
189
- steps,
190
- orientation,
191
- }),
192
- [activeId, activeIndex, setActiveStep, steps, orientation]
193
- );
188
+ const contextValue = React.useMemo<StepperContextValue>(
189
+ () => ({
190
+ activeId,
191
+ activeIndex,
192
+ setActiveStep,
193
+ steps,
194
+ orientation,
195
+ }),
196
+ [activeId, activeIndex, setActiveStep, steps, orientation]
197
+ );
198
+
199
+ return (
200
+ <StepperContext.Provider value={contextValue}>
201
+ <div
202
+ ref={ref}
203
+ aria-label={ariaLabel ?? "Progress"}
204
+ className={cn(
205
+ "group/stepper flex data-[orientation=vertical]:flex-col",
206
+ className
207
+ )}
208
+ data-hook={dataHook}
209
+ data-layout={layout}
210
+ data-orientation={orientation}
211
+ data-slot="stepper"
212
+ data-tracking-el={trackingEl}
213
+ data-tracking-label={trackingLabel}
214
+ role="group"
215
+ {...props}
216
+ />
217
+ </StepperContext.Provider>
218
+ );
219
+ }
220
+
221
+ // forwardRef erases the generic type parameter, so cast the wrapped component
222
+ // back to a generic call signature — this keeps `TStepId` inference at the call
223
+ // site while still forwarding the ref. Mirrors the Tabs component.
224
+ const Stepper = React.forwardRef(StepperInner) as (<
225
+ TStepId extends string = string,
226
+ >(
227
+ props: StepperProps<TStepId> & React.RefAttributes<HTMLDivElement>
228
+ ) => React.ReactElement | null) & { displayName?: string };
194
229
 
195
- return (
196
- <StepperContext.Provider value={contextValue}>
197
- <div
198
- ref={ref}
199
- aria-label={ariaLabel ?? "Progress"}
200
- className={cn(
201
- "group/stepper flex data-[orientation=vertical]:flex-col",
202
- className
203
- )}
204
- data-hook={dataHook}
205
- data-layout={layout}
206
- data-orientation={orientation}
207
- data-slot="stepper"
208
- data-tracking-el={trackingEl}
209
- data-tracking-label={trackingLabel}
210
- role="group"
211
- {...props}
212
- />
213
- </StepperContext.Provider>
214
- );
215
- }
216
- );
217
230
  Stepper.displayName = "Stepper";
218
231
 
219
232
  /* -------------------------------------------------------------------------- */