@brightlocal/ui-components 3.3.0 → 3.4.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.
@@ -0,0 +1,445 @@
1
+ "use client";
2
+
3
+ import * as React from "react";
4
+ import { cva } from "class-variance-authority";
5
+
6
+ import { cn } from "@brightlocal/ui-components/lib/utils";
7
+
8
+ /* -------------------------------------------------------------------------------------------------
9
+ * Context
10
+ * -----------------------------------------------------------------------------------------------*/
11
+
12
+ /**
13
+ * How each term sits against its value.
14
+ * - `inline` — term column beside the value, every value starts on the same line
15
+ * - `stacked` — term above the value
16
+ * - `responsive` — stacked below the `sm` breakpoint, inline from `sm` up
17
+ * - `container` — stacked until the nearest `@container` is `@md` (28rem) wide,
18
+ * for lists in narrow panels on wide screens
19
+ * - `grid` — stacked items flowing into as many columns as fit (facts, plan limits)
20
+ */
21
+ export type DescriptionListLayout =
22
+ "inline" | "stacked" | "responsive" | "container" | "grid";
23
+
24
+ /**
25
+ * Where the value sits in an `inline` row (other layouts ignore it).
26
+ * - `start` — values line up in a column after the term
27
+ * - `end` — values pushed to the row's end (receipts, totals, counts)
28
+ */
29
+ export type DescriptionListAlign = "start" | "end";
30
+
31
+ type DescriptionListContextValue = {
32
+ layout: DescriptionListLayout;
33
+ align: DescriptionListAlign;
34
+ /** Rows share one auto-sized term column (subgrid). */
35
+ autoTerm: boolean;
36
+ };
37
+
38
+ const DescriptionListContext = React.createContext<DescriptionListContextValue>(
39
+ { layout: "inline", align: "start", autoTerm: false }
40
+ );
41
+
42
+ /* -------------------------------------------------------------------------------------------------
43
+ * Variants
44
+ * -----------------------------------------------------------------------------------------------*/
45
+
46
+ const descriptionListVariants = cva("min-w-0", {
47
+ variants: {
48
+ layout: {
49
+ inline: "flex flex-col",
50
+ stacked: "flex flex-col",
51
+ responsive: "flex flex-col",
52
+ container: "flex flex-col",
53
+ // Columns at least 8rem wide, as many as fit: a plan's limits or a record's
54
+ // facts reflow from one column on a phone to a full row on desktop.
55
+ grid: "grid grid-cols-[repeat(auto-fill,minmax(8rem,1fr))] gap-x-6 gap-y-4",
56
+ },
57
+ divided: {
58
+ // Lines between rows only: no padding above the first row or below the
59
+ // last, so the list sits at its container's own spacing.
60
+ true: [
61
+ "divide-border divide-y",
62
+ "[&>[data-slot=description-list-item]]:py-3",
63
+ "[&>[data-slot=description-list-item]:first-child]:pt-0",
64
+ "[&>[data-slot=description-list-item]:last-child]:pb-0",
65
+ ],
66
+ false: "",
67
+ },
68
+ },
69
+ compoundVariants: [
70
+ { layout: "inline", divided: false, className: "gap-3" },
71
+ { layout: "stacked", divided: false, className: "gap-3" },
72
+ { layout: "responsive", divided: false, className: "gap-3" },
73
+ { layout: "container", divided: false, className: "gap-3" },
74
+ ],
75
+ defaultVariants: {
76
+ layout: "inline",
77
+ divided: false,
78
+ },
79
+ });
80
+
81
+ const descriptionListItemVariants = cva("flex min-w-0", {
82
+ variants: {
83
+ layout: {
84
+ inline: "flex-row items-baseline gap-4",
85
+ stacked: "flex-col gap-1",
86
+ responsive: "flex-col gap-1 sm:flex-row sm:items-baseline sm:gap-4",
87
+ container: "flex-col gap-1 @md:flex-row @md:items-baseline @md:gap-4",
88
+ grid: "flex-col gap-1",
89
+ },
90
+ },
91
+ defaultVariants: {
92
+ layout: "inline",
93
+ },
94
+ });
95
+
96
+ const descriptionListTermVariants = cva(
97
+ "text-muted-foreground text-body-sm shrink-0",
98
+ {
99
+ variants: {
100
+ layout: {
101
+ inline: "w-(--dl-term-width)",
102
+ stacked: "",
103
+ responsive: "sm:w-(--dl-term-width)",
104
+ container: "@md:w-(--dl-term-width)",
105
+ grid: "",
106
+ },
107
+ },
108
+ defaultVariants: {
109
+ layout: "inline",
110
+ },
111
+ }
112
+ );
113
+
114
+ /* An auto-width term column has to be shared by every row, so the list
115
+ becomes a two-column grid and each row a subgrid of it. Only where the term
116
+ sits beside its value: below the breakpoint the row still stacks. */
117
+ const autoTermListClasses: Partial<Record<DescriptionListLayout, string>> = {
118
+ inline: "grid grid-cols-[max-content_1fr] gap-x-4",
119
+ responsive: "sm:grid sm:grid-cols-[max-content_1fr] sm:gap-x-4",
120
+ container: "@md:grid @md:grid-cols-[max-content_1fr] @md:gap-x-4",
121
+ };
122
+
123
+ const autoTermItemClasses: Partial<Record<DescriptionListLayout, string>> = {
124
+ inline: "col-span-2 grid grid-cols-subgrid",
125
+ responsive: "sm:col-span-2 sm:grid sm:grid-cols-subgrid",
126
+ container: "@md:col-span-2 @md:grid @md:grid-cols-subgrid",
127
+ };
128
+
129
+ /** Layouts where the term can sit beside its value. */
130
+ const SIDE_BY_SIDE: ReadonlyArray<DescriptionListLayout> = [
131
+ "inline",
132
+ "responsive",
133
+ "container",
134
+ ];
135
+
136
+ /* -------------------------------------------------------------------------------------------------
137
+ * DescriptionList
138
+ * -----------------------------------------------------------------------------------------------*/
139
+
140
+ /**
141
+ * Props for the DescriptionList root.
142
+ * Extends native `<dl>` props with layout options and testing/analytics attributes.
143
+ */
144
+ export interface DescriptionListProps extends React.ComponentProps<"dl"> {
145
+ /**
146
+ * Data hook for automated testing (required).
147
+ * @example "review-details", "plan-limits"
148
+ */
149
+ dataHook: string;
150
+ /**
151
+ * Tracking element identifier for analytics.
152
+ * @default "description-list"
153
+ */
154
+ trackingEl?: string;
155
+ /**
156
+ * Tracking label for analytics context.
157
+ */
158
+ trackingLabel?: string;
159
+ /**
160
+ * How each term sits against its value.
161
+ * @default "inline"
162
+ */
163
+ layout?: DescriptionListLayout;
164
+ /**
165
+ * Width of the term column when the term sits beside its value. A number is
166
+ * pixels; `"auto"` sizes the column to the longest term.
167
+ * Ignored by `stacked` and `grid`, and by `align="end"` on `inline`.
168
+ * @default 128
169
+ */
170
+ termWidth?: number | "auto";
171
+ /**
172
+ * Where the value sits in an `inline` row. `end` pushes values to the row's
173
+ * end, for receipts and totals; other layouts ignore it.
174
+ * @default "start"
175
+ */
176
+ align?: DescriptionListAlign;
177
+ /**
178
+ * Draw a hairline between items. Not used by the `grid` layout.
179
+ * @default false
180
+ */
181
+ divided?: boolean;
182
+ }
183
+
184
+ /**
185
+ * Label-and-value pairs describing one record: the details of a review, the
186
+ * read view of a settings card, a receipt. Renders a semantic `<dl>`.
187
+ *
188
+ * For several records compared by the same attributes, use Table instead.
189
+ *
190
+ * @example
191
+ * ```tsx
192
+ * <DescriptionList dataHook="review-details">
193
+ * <DescriptionListItem>
194
+ * <DescriptionListTerm>Source</DescriptionListTerm>
195
+ * <DescriptionListDetails>Google</DescriptionListDetails>
196
+ * </DescriptionListItem>
197
+ * </DescriptionList>
198
+ * ```
199
+ */
200
+ const DescriptionList = React.forwardRef<
201
+ HTMLDListElement,
202
+ DescriptionListProps
203
+ >(
204
+ (
205
+ {
206
+ className,
207
+ style,
208
+ layout = "inline",
209
+ termWidth = 128,
210
+ align = "start",
211
+ divided = false,
212
+ dataHook,
213
+ trackingEl,
214
+ trackingLabel,
215
+ ...props
216
+ },
217
+ ref
218
+ ) => {
219
+ const sideBySide =
220
+ SIDE_BY_SIDE.includes(layout) &&
221
+ !(align === "end" && layout === "inline");
222
+ const autoTerm = sideBySide && termWidth === "auto";
223
+ const context = React.useMemo(
224
+ () => ({ layout, align, autoTerm }),
225
+ [layout, align, autoTerm]
226
+ );
227
+
228
+ return (
229
+ <DescriptionListContext.Provider value={context}>
230
+ <dl
231
+ ref={ref}
232
+ className={cn(
233
+ descriptionListVariants({
234
+ layout,
235
+ divided: layout === "grid" ? false : divided,
236
+ }),
237
+ autoTerm && autoTermListClasses[layout],
238
+ className
239
+ )}
240
+ data-align={align}
241
+ data-hook={dataHook}
242
+ data-layout={layout}
243
+ data-slot="description-list"
244
+ data-tracking-el={trackingEl || "description-list"}
245
+ data-tracking-label={trackingLabel}
246
+ style={
247
+ {
248
+ ...(typeof termWidth === "number" && {
249
+ "--dl-term-width": `${termWidth}px`,
250
+ }),
251
+ ...style,
252
+ } as React.CSSProperties
253
+ }
254
+ {...props}
255
+ />
256
+ </DescriptionListContext.Provider>
257
+ );
258
+ }
259
+ );
260
+ DescriptionList.displayName = "DescriptionList";
261
+
262
+ /* -------------------------------------------------------------------------------------------------
263
+ * DescriptionListItem
264
+ * -----------------------------------------------------------------------------------------------*/
265
+
266
+ /**
267
+ * Props for DescriptionListItem — one term and its value.
268
+ */
269
+ export interface DescriptionListItemProps extends React.ComponentProps<"div"> {
270
+ /**
271
+ * Data hook for automated testing.
272
+ */
273
+ dataHook?: string;
274
+ }
275
+
276
+ /**
277
+ * One term and its value. Renders a `<div>`, the grouping element HTML allows
278
+ * inside a `<dl>`.
279
+ */
280
+ const DescriptionListItem = React.forwardRef<
281
+ HTMLDivElement,
282
+ DescriptionListItemProps
283
+ >(({ className, dataHook, ...props }, ref) => {
284
+ const { layout, align, autoTerm } = React.useContext(DescriptionListContext);
285
+ const endAligned = align === "end" && layout === "inline";
286
+
287
+ return (
288
+ <div
289
+ ref={ref}
290
+ className={cn(
291
+ descriptionListItemVariants({ layout }),
292
+ endAligned && "justify-between",
293
+ autoTerm && autoTermItemClasses[layout],
294
+ className
295
+ )}
296
+ data-hook={dataHook}
297
+ data-slot="description-list-item"
298
+ {...props}
299
+ />
300
+ );
301
+ });
302
+ DescriptionListItem.displayName = "DescriptionListItem";
303
+
304
+ /* -------------------------------------------------------------------------------------------------
305
+ * DescriptionListTerm
306
+ * -----------------------------------------------------------------------------------------------*/
307
+
308
+ /**
309
+ * Props for DescriptionListTerm — the label.
310
+ */
311
+ export interface DescriptionListTermProps extends React.ComponentProps<"dt"> {
312
+ /**
313
+ * Data hook for automated testing.
314
+ */
315
+ dataHook?: string;
316
+ }
317
+
318
+ /**
319
+ * The label of a pair. Muted, `text-body-sm`.
320
+ */
321
+ const DescriptionListTerm = React.forwardRef<
322
+ HTMLElement,
323
+ DescriptionListTermProps
324
+ >(({ className, dataHook, ...props }, ref) => {
325
+ const { layout, align, autoTerm } = React.useContext(DescriptionListContext);
326
+
327
+ return (
328
+ <dt
329
+ ref={ref}
330
+ className={cn(
331
+ // The fixed width applies only when the term sits beside its value in
332
+ // a fixed column; an end-aligned or auto-width term sizes to its text.
333
+ descriptionListTermVariants({
334
+ layout: align === "end" || autoTerm ? "stacked" : layout,
335
+ }),
336
+ className
337
+ )}
338
+ data-hook={dataHook}
339
+ data-slot="description-list-term"
340
+ {...props}
341
+ />
342
+ );
343
+ });
344
+ DescriptionListTerm.displayName = "DescriptionListTerm";
345
+
346
+ /* -------------------------------------------------------------------------------------------------
347
+ * DescriptionListDetails
348
+ * -----------------------------------------------------------------------------------------------*/
349
+
350
+ /**
351
+ * Props for DescriptionListDetails — the value.
352
+ */
353
+ export interface DescriptionListDetailsProps extends React.ComponentProps<"dd"> {
354
+ /**
355
+ * Data hook for automated testing.
356
+ */
357
+ dataHook?: string;
358
+ /**
359
+ * Text colour of the value. Use `muted` for an empty value ("Not set").
360
+ * @default "foreground"
361
+ */
362
+ color?: "foreground" | "muted";
363
+ }
364
+
365
+ /**
366
+ * The value of a pair: text, a Badge, a Rating, a Link or an icon with text.
367
+ * Long values wrap.
368
+ */
369
+ const DescriptionListDetails = React.forwardRef<
370
+ HTMLElement,
371
+ DescriptionListDetailsProps
372
+ >(({ className, color = "foreground", dataHook, ...props }, ref) => {
373
+ const { layout, align } = React.useContext(DescriptionListContext);
374
+ const endAligned = align === "end" && layout === "inline";
375
+
376
+ return (
377
+ <dd
378
+ ref={ref}
379
+ className={cn(
380
+ "text-body-sm min-w-0 flex-1 break-words",
381
+ color === "muted" ? "text-muted-foreground" : "text-foreground",
382
+ endAligned && "text-right tabular-nums",
383
+ className
384
+ )}
385
+ data-hook={dataHook}
386
+ data-slot="description-list-details"
387
+ {...props}
388
+ />
389
+ );
390
+ });
391
+ DescriptionListDetails.displayName = "DescriptionListDetails";
392
+
393
+ /* -------------------------------------------------------------------------------------------------
394
+ * DescriptionListIconText
395
+ * -----------------------------------------------------------------------------------------------*/
396
+
397
+ /**
398
+ * Props for DescriptionListIconText — an icon or logo beside a text value.
399
+ */
400
+ export interface DescriptionListIconTextProps extends React.ComponentProps<"span"> {
401
+ /**
402
+ * The icon or logo, sized to 16px.
403
+ */
404
+ icon: React.ReactNode;
405
+ }
406
+
407
+ /**
408
+ * An icon or logo beside a text value, such as a review source and its name.
409
+ */
410
+ const DescriptionListIconText = React.forwardRef<
411
+ HTMLSpanElement,
412
+ DescriptionListIconTextProps
413
+ >(({ className, icon, children, ...props }, ref) => (
414
+ <span
415
+ ref={ref}
416
+ className={cn(
417
+ "inline-flex max-w-full items-center gap-2 align-bottom [&_svg:not([class*='size-'])]:size-4",
418
+ className
419
+ )}
420
+ data-slot="description-list-icon-text"
421
+ {...props}
422
+ >
423
+ <span
424
+ aria-hidden="true"
425
+ className="inline-flex size-4 shrink-0 items-center justify-center"
426
+ >
427
+ {icon}
428
+ </span>
429
+ <span className="min-w-0">{children}</span>
430
+ </span>
431
+ ));
432
+ DescriptionListIconText.displayName = "DescriptionListIconText";
433
+
434
+ /* -------------------------------------------------------------------------------------------------
435
+ * Exports
436
+ * -----------------------------------------------------------------------------------------------*/
437
+
438
+ export {
439
+ DescriptionList,
440
+ DescriptionListItem,
441
+ DescriptionListTerm,
442
+ DescriptionListDetails,
443
+ DescriptionListIconText,
444
+ descriptionListVariants,
445
+ };