ab-nextjs-components 0.1.13 โ†’ 0.1.14

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.
Files changed (53) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +30 -0
  3. package/ab-app-bar/index.tsx +39 -10
  4. package/ab-app-bar/styles.module.css +43 -4
  5. package/ab-bottom-drawer/index.tsx +71 -0
  6. package/ab-bottom-drawer/styles.module.css +66 -0
  7. package/ab-breadcrumbs/index.tsx +92 -0
  8. package/ab-breadcrumbs/styles.module.css +54 -0
  9. package/ab-button/helpers.ts +6 -1
  10. package/ab-button/index.tsx +8 -2
  11. package/ab-button/styles.module.css +39 -0
  12. package/ab-card/styles.module.css +1 -1
  13. package/ab-carousel/styles.module.css +1 -1
  14. package/ab-chip/index.tsx +16 -4
  15. package/ab-chip/styles.module.css +12 -1
  16. package/ab-confirm-drawer/index.tsx +97 -0
  17. package/ab-confirm-drawer/styles.module.css +41 -0
  18. package/ab-drawer/index.tsx +307 -0
  19. package/ab-drawer/styles.module.css +127 -0
  20. package/ab-drawer/use-ab-drawer.ts +89 -0
  21. package/ab-drawer-list/index.tsx +118 -0
  22. package/ab-drawer-list/styles.module.css +65 -0
  23. package/ab-flow-diagram/styles.module.css +2 -2
  24. package/ab-icon/builtin.ts +4 -0
  25. package/ab-icon-button/index.tsx +12 -1
  26. package/ab-icon-button/styles.module.css +1 -1
  27. package/ab-install-snippet/index.tsx +51 -29
  28. package/ab-install-snippet/styles.module.css +34 -2
  29. package/ab-kbd/styles.module.css +1 -1
  30. package/ab-list/index.tsx +107 -0
  31. package/ab-list/styles.module.css +82 -0
  32. package/ab-locale-switcher/index.tsx +42 -10
  33. package/ab-locale-switcher/styles.module.css +4 -4
  34. package/ab-navbar/styles.module.css +20 -2
  35. package/ab-navbar/view.tsx +7 -4
  36. package/ab-package-card/index.tsx +49 -2
  37. package/ab-package-card/styles.module.css +40 -0
  38. package/ab-search-trigger/index.tsx +17 -2
  39. package/ab-search-trigger/styles.module.css +27 -1
  40. package/ab-sidebar/index.tsx +5 -2
  41. package/ab-sidebar/styles.module.css +48 -5
  42. package/ab-sidebar/view.tsx +14 -4
  43. package/ab-theme-toggle/index.tsx +21 -6
  44. package/ab-theme-toggle/styles.module.css +18 -3
  45. package/ab-toc/index.tsx +9 -2
  46. package/ab-toc/styles.module.css +20 -8
  47. package/ab-version-switcher/index.tsx +143 -0
  48. package/ab-version-switcher/styles.module.css +76 -0
  49. package/index.ts +27 -0
  50. package/package.json +18 -3
  51. package/server/ab-button/index.tsx +6 -2
  52. package/server/ab-button/styles.module.css +39 -0
  53. package/types/index.d.ts +19 -0
@@ -181,3 +181,42 @@ a.abButton[data-type="outlined"] {
181
181
  line-height: 32px; /* ๐Ÿ“ */
182
182
  }
183
183
  a.abButton.abButtonRounded { border-radius: 9999px; } /* ๐Ÿ’Š */
184
+
185
+ /* ===== ๐Ÿ”ท 0.1.14 (P16, Home fidelity spec ยง4 CTAs): shape="rounded" ยท size="md" ยท type="secondary" =====
186
+ * Doubled class (0,3,0+) beats the theme's `button[data-type="filled"]` (0,1,1) and its :hover (0,3,1 โ†’ we use 0,5,0). */
187
+ .abButton.abButton[data-shape="rounded"] {
188
+ gap: 6px; /* ๐Ÿงฑ icon โ†” label */
189
+ border-radius: var(--ab-radius-button, 10px); /* ๐Ÿ”ท */
190
+ padding: 0 var(--ab-button-padding-inline, 16px); /* ๐Ÿ“ฆ */
191
+ font-size: 14px; font-weight: 650; line-height: 1; white-space: nowrap; /* ๐Ÿ”ค */
192
+ overflow: visible; /* ๐ŸŒ— the primary shadow must show */
193
+ }
194
+ .abButton.abButton[data-size="md"] { height: var(--ab-button-height, 40px); box-sizing: border-box; } /* ๐Ÿ“ */
195
+ .abButton.abButton[data-shape="rounded"] .abButtonSlot { width: 18px; height: 18px; } /* ๐Ÿ–ผ๏ธ 18px icons */
196
+ .abButton.abButton[data-shape="rounded"] .abButtonSlot svg { width: 100%; height: 100%; }
197
+ /* ๐Ÿฅ‰ primary (filled) */
198
+ .abButton.abButton[data-shape="rounded"][data-type="filled"] {
199
+ background: var(--ab-color-btn, #8b6340); color: var(--ab-color-btn-text, #fff); /* ๐ŸŽจ AA (theme 0.3.5) */
200
+ border: 0; box-shadow: var(--ab-shadow-button, 0 1px 0 rgb(255 255 255 / 0.2) inset, 0 4px 12px rgb(139 99 64 / 0.25)); /* โœจ */
201
+ }
202
+ .abButton.abButton[data-shape="rounded"][data-type="filled"]:not(:disabled, [aria-disabled="true"]):hover {
203
+ background: color-mix(in srgb, var(--ab-color-btn, #8b6340) 90%, #000); /* ๐Ÿ–ฑ๏ธ */
204
+ }
205
+ /* โšช secondary */
206
+ .abButton.abButton[data-type="secondary"] {
207
+ border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); background: var(--ab-color-card, #fff); color: var(--ab-color-text, #211a16); /* ๐ŸŽจ */
208
+ box-sizing: border-box;
209
+ }
210
+ .abButton.abButton[data-type="secondary"]:not(:disabled, [aria-disabled="true"]):hover {
211
+ background: linear-gradient(var(--ab-color-hover, rgb(166 124 82 / 0.08)), var(--ab-color-hover, rgb(166 124 82 / 0.08))), var(--ab-color-card, #fff); /* ๐Ÿ–ฑ๏ธ tint over the card */
212
+ }
213
+ .abButton.abButton[data-shape="rounded"]:not(:disabled, [aria-disabled="true"]):active { transform: translateY(1px); } /* ๐Ÿ‘‡ */
214
+ .abButton.abButton[data-shape="rounded"]:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; } /* โ™ฟ */
215
+ /* ๐Ÿ“ฑ touch widths: 44px, 14.5px (mock .M .btn; the app sets flex: 1) */
216
+ @media (max-width: 767px) {
217
+ .abButton.abButton[data-size="md"] { height: var(--ab-button-height-touch, 44px); }
218
+ .abButton.abButton[data-shape="rounded"][data-size="md"] { font-size: 14.5px; }
219
+ }
220
+ @media (prefers-reduced-motion: reduce) {
221
+ .abButton.abButton[data-shape="rounded"]:active { transform: none; } /* โ™ฟ no nudge */
222
+ }
@@ -58,7 +58,7 @@
58
58
  .abCardLink::after { content: ''; position: absolute; inset: 0; border-radius: inherit; } /* ๐Ÿงฒ whole card clickable */
59
59
  .abCard[data-linked='true']:hover { background: var(--ab-color-surface-container, rgb(0 0 0 / 0.06)); } /* ๐Ÿ–ฑ๏ธ */
60
60
  .abCard:focus-within:has(.abCardLink:focus-visible) {
61
- outline: var(--ab-focus-ring-width, 2px) solid var(--ab-color-primary, #8f4c38); /* โ™ฟ ring on the card */
61
+ outline: var(--ab-focus-ring-width, 2px) solid var(--ab-color-accent, var(--ab-color-primary, #8f4c38)); /* โ™ฟ ring on the card */
62
62
  outline-offset: var(--ab-focus-ring-offset, 2px); /* โ™ฟ */
63
63
  }
64
64
  .abCardLink:focus-visible { outline: none; } /* โ™ฟ the card shows the ring */
@@ -101,7 +101,7 @@
101
101
  /* ๐ŸŽจ hover / ๐Ÿค press motion: .ab-motion-interactive + .ab-motion-press (ab-nextjs-animations) */
102
102
  }
103
103
  .nav:hover {
104
- background-color: color-mix(in srgb, currentColor 8%, transparent); /* ๐ŸŒซ๏ธ */
104
+ background-color: var(--ab-color-hover, color-mix(in srgb, currentColor 8%, transparent)); /* ๐ŸŒซ๏ธ */
105
105
  }
106
106
  .nav[data-variant='filled'] {
107
107
  border-color: transparent;
package/ab-chip/index.tsx CHANGED
@@ -48,6 +48,8 @@ import styles from './styles.module.css';
48
48
 
49
49
  // ๐ŸŽจ dot colours
50
50
  export type AbChipDot = 'sage' | 'bronze';
51
+ // ๐ŸŽจ 0.1.14 (P16): Home chip tones ยท 'accent' = --tint bg + --accent-text ยท 'sage' = the `beta` chip
52
+ export type AbChipTone = 'neutral' | 'accent' | 'sage';
51
53
 
52
54
  // โš™๏ธ props
53
55
  export interface AbChipProps {
@@ -57,14 +59,24 @@ export interface AbChipProps {
57
59
  as?: 'span' | 'li'; // ๐Ÿงฑ 'li' inside a <ul> for lists of chips
58
60
  className?: string; // ๐Ÿท๏ธ
59
61
  style?: CSSProperties; // ๐ŸŽจ
62
+ size?: 'md' | 'sm'; // ๐Ÿ“ 0.1.14 (P16): 'sm' = the 20px Home chip (version, count, New)
63
+ shape?: 'pill' | 'rounded'; // ๐Ÿ”ท 0.1.14: 'rounded' = 6px radius (default pill)
64
+ mono?: boolean; // โŒจ๏ธ 0.1.14: Roboto Mono 11/600 (versions, package names)
65
+ tone?: AbChipTone; // ๐ŸŽจ 0.1.14 (default 'neutral' = the legacy outline chip)
60
66
  }
61
67
 
62
68
  /** ๐Ÿท๏ธ Static chip: plain text, never interactive (use AbButton for actions). */
63
- export function AbChip({ children, dot, icon, as: Tag = 'span', className, style }: AbChipProps): ReactElement {
64
- const tone = dot === true ? 'bronze' : dot || undefined; // ๐ŸŽจ resolve dot colour
69
+ export function AbChip({ children, dot, icon, as: Tag = 'span', className, style, size = 'md', shape = 'pill', mono = false, tone = 'neutral' }: AbChipProps): ReactElement {
70
+ const dotTone = dot === true ? 'bronze' : dot || undefined; // ๐ŸŽจ resolve dot colour
65
71
  return (
66
- <Tag className={clsx('AbChip', styles.chip, className)} style={style} data-ab-part="chip">
67
- {tone ? <span className={styles.dot} data-tone={tone} aria-hidden="true" /> : null /* ๐ŸŸข decorative */}
72
+ <Tag
73
+ className={clsx('AbChip', styles.chip, mono && styles.mono, className)} style={style} data-ab-part="chip"
74
+ data-size={size === 'sm' ? 'sm' : undefined} // ๐Ÿ“ P16
75
+ data-shape={shape === 'rounded' ? 'rounded' : undefined} // ๐Ÿ”ท
76
+ data-tone={tone === 'neutral' ? undefined : tone} // ๐ŸŽจ
77
+ data-mono={mono ? 'true' : undefined} // โŒจ๏ธ
78
+ >
79
+ {dotTone ? <span className={styles.dot} data-tone={dotTone} aria-hidden="true" /> : null /* ๐ŸŸข decorative */}
68
80
  {icon ? <span className={styles.icon} aria-hidden="true">{icon}</span> : null /* ๐Ÿ–ผ๏ธ decorative */}
69
81
  <span>{children}</span>
70
82
  </Tag>
@@ -43,7 +43,7 @@
43
43
  gap: 0.375rem; /* ๐Ÿงฑ */
44
44
  padding: 0.25rem 0.75rem; /* ๐Ÿงฑ */
45
45
  border-radius: 9999px; /* ๐Ÿ’Š */
46
- border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* ๐Ÿ–Š๏ธ */
46
+ border: 1px solid var(--ab-color-border, var(--ab-color-outline-variant, rgb(0 0 0 / 0.12))); /* ๐Ÿ–Š๏ธ */
47
47
  background: var(--ab-color-surface-container, transparent); /* ๐ŸŽจ */
48
48
  color: var(--ab-color-on-surface, currentColor); /* ๐ŸŽจ */
49
49
  font-size: 0.875rem; /* ๐Ÿ”ก */
@@ -85,3 +85,14 @@
85
85
  width: 1em; /* ๐Ÿ“ */
86
86
  height: 1em; /* ๐Ÿ“ */
87
87
  }
88
+
89
+ /* ===== ๐Ÿ  0.1.14 (P16, Home spec ยง2/ยง4): size="sm" ยท shape="rounded" ยท mono ยท tone ===== */
90
+ .chip[data-size='sm'] {
91
+ height: var(--ab-chip-height, 20px); box-sizing: border-box; /* ๐Ÿ“ */
92
+ padding: 0 var(--ab-chip-padding-inline, 7px); gap: 4px; /* ๐Ÿ“ฆ */
93
+ border: 0; font-size: 11px; font-weight: 600; line-height: 1; /* ๐Ÿ”ค mock .chip */
94
+ }
95
+ .chip[data-shape='rounded'] { border-radius: var(--ab-radius-chip, 6px); } /* ๐Ÿ”ท */
96
+ .chip[data-mono='true'] { font-family: var(--ab-font-code, 'Roboto Mono', ui-monospace, monospace); } /* โŒจ๏ธ */
97
+ .chip[data-tone='accent'] { background: var(--ab-color-tint, #f4e7db); color: var(--ab-color-accent-text, #88603d); border-color: transparent; } /* ๐Ÿฅ‰ */
98
+ .chip[data-tone='sage'] { background: rgb(119 141 121 / 0.12); color: var(--ab-color-sage-accent, #566a58); border-color: transparent; } /* ๐ŸŒฟ beta โ™ฟ AA (John): fallback = theme 0.3.5 light value */
@@ -0,0 +1,97 @@
1
+ /*
2
+ * @license MIT
3
+ * ~~~~~~~~~~~~
4
+ * ab-nextjs-components
5
+ * ~~~~~~~~~~~~
6
+ * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
7
+ *
8
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ * of this software and associated documentation files (the 'Software'), to deal
10
+ * in the Software without restriction, including without limitation the rights
11
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ * copies of the Software, and to permit persons to whom the Software is
13
+ * furnished to do so, subject to the following conditions:
14
+ *
15
+ * The above copyright notice and this permission notice shall be included in all
16
+ * copies or substantial portions of the Software.
17
+ *
18
+ * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ * SOFTWARE.
25
+ *
26
+ * @project: ab-nextjs-components
27
+ * @name: AbConfirmDrawer (G53 preset)
28
+ * @file: ab-confirm-drawer/index.tsx
29
+ * @type: Client component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * 1+|> <AbConfirmDrawer scope="main" open={d.open} onClose={d.close} title="Discard changes?"
34
+ * -|> message="Your edits will be lost." confirmLabel="Discard" tone="danger" onConfirm={discard} />
35
+ */
36
+
37
+ /*
38
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
39
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
40
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
41
+ */
42
+
43
+
44
+ 'use client';
45
+
46
+ // โš›๏ธ React
47
+ import type { ReactElement, ReactNode } from 'react';
48
+ // ๐Ÿงต classes
49
+ import clsx from 'clsx';
50
+ // ๐Ÿ—„๏ธ the drawer
51
+ import AbDrawer, { type AbDrawerProps } from '../ab-drawer';
52
+ // ๐Ÿ”˜ the house buttons
53
+ import AbButton from '../ab-button';
54
+ // ๐ŸŽจ styles
55
+ import styles from './styles.module.css';
56
+
57
+ /** โš™๏ธ props: every AbDrawer prop (minus children / footer), plus the decision */
58
+ export interface AbConfirmDrawerProps extends Omit<AbDrawerProps, 'children' | 'footer'> {
59
+ message?: ReactNode; // ๐Ÿ“ what happens if you confirm
60
+ confirmLabel?: string; // โœ… default "Confirm"
61
+ cancelLabel?: string; // โŒ default "Cancel"
62
+ onConfirm: () => void; // โœ… the drawer closes after it (unless `closeOnConfirm={false}`)
63
+ onCancel?: () => void; // โŒ default: just close
64
+ tone?: 'default' | 'danger'; // ๐ŸŽจ `danger` = destructive confirm
65
+ busy?: boolean; // โณ disables both buttons + spinner on confirm
66
+ closeOnConfirm?: boolean; // ๐Ÿšช default true
67
+ }
68
+
69
+ /**
70
+ * โ“ AbConfirmDrawer โ€” a yes / no decision that belongs to a region (e.g. "Discard changes?" inside main).
71
+ * Defaults to `side="bottom"`; Escape / scrim / close = cancel. For an app-wide blocking decision use a
72
+ * centred dialog instead (layout-rule guide, "Drawer, menu or dialog?").
73
+ */
74
+ const AbConfirmDrawer = ({ message, confirmLabel = 'Confirm', cancelLabel = 'Cancel', onConfirm, onCancel, tone = 'default', busy = false, closeOnConfirm = true, onClose, className, side = 'bottom', ...drawer }: AbConfirmDrawerProps): ReactElement => {
75
+ const cancel = () => { onCancel?.(); onClose(); }; // โŒ then ๐Ÿšช
76
+ const confirm = () => { onConfirm(); if (closeOnConfirm) onClose(); }; // โœ… then ๐Ÿšช
77
+ return (
78
+ <AbDrawer
79
+ {...drawer}
80
+ side={side}
81
+ onClose={cancel} // โŽ‹ Escape / scrim / โœ• all mean "no"
82
+ className={clsx('AbConfirmDrawer', className)}
83
+ footer={
84
+ <>
85
+ <AbButton type="text" label={cancelLabel} onClick={cancel} disabled={busy} />
86
+ <AbButton type="filled" label={confirmLabel} onClick={confirm} isLoading={busy} disabled={busy} className={tone === 'danger' ? styles.abConfirmDanger : undefined} />
87
+ </>
88
+ }
89
+ >
90
+ {message != null && <div className={styles.abConfirmMessage} data-ab-part="confirm-message">{message}</div>}
91
+ </AbDrawer>
92
+ );
93
+ };
94
+
95
+ // ๐Ÿ“ฆ exports
96
+ export default AbConfirmDrawer;
97
+ export { AbConfirmDrawer };
@@ -0,0 +1,41 @@
1
+ /*
2
+ * @license MIT
3
+ * ~~~~~~~~~~~~
4
+ * ab-nextjs-components
5
+ * ~~~~~~~~~~~~
6
+ * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
7
+ *
8
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ * of this software and associated documentation files (the 'Software'), to deal
10
+ * in the Software without restriction, including without limitation the rights
11
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ * copies of the Software, and to permit persons to whom the Software is
13
+ * furnished to do so, subject to the following conditions:
14
+ *
15
+ * The above copyright notice and this permission notice shall be included in all
16
+ * copies or substantial portions of the Software.
17
+ *
18
+ * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ * SOFTWARE.
25
+ *
26
+ * @project: ab-nextjs-components
27
+ * @name: AbConfirmDrawer styles
28
+ * @file: ab-confirm-drawer/styles.module.css
29
+ * @type: CSS module
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
33
+ /*
34
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
36
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37
+ */
38
+
39
+
40
+ .abConfirmMessage { margin: 0; line-height: 1.5; } /* ๐Ÿ“ */
41
+ .abConfirmDanger { --ab-button-background-color: var(--ab-color-error, #b3261e); --ab-button-text-color: var(--ab-color-on-error, #fff); } /* ๐Ÿšจ destructive */
@@ -0,0 +1,307 @@
1
+ /*
2
+ * @license MIT
3
+ * ~~~~~~~~~~~~
4
+ * ab-nextjs-components
5
+ * ~~~~~~~~~~~~
6
+ * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
7
+ *
8
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ * of this software and associated documentation files (the 'Software'), to deal
10
+ * in the Software without restriction, including without limitation the rights
11
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ * copies of the Software, and to permit persons to whom the Software is
13
+ * furnished to do so, subject to the following conditions:
14
+ *
15
+ * The above copyright notice and this permission notice shall be included in all
16
+ * copies or substantial portions of the Software.
17
+ *
18
+ * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ * SOFTWARE.
25
+ *
26
+ * @project: ab-nextjs-components
27
+ * @name: AbDrawer (G53)
28
+ * @file: ab-drawer/index.tsx
29
+ * @type: Client component (SSR: in-flow no-JS fallback)
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * 1+|> const drawer = useAbDrawer('main')
34
+ * -|> <button {...drawer.triggerProps}>Filters</button>
35
+ * -|> <AbDrawer {...drawer.drawerProps} side="end" title="Filters">โ€ฆ</AbDrawer>
36
+ */
37
+
38
+ /*
39
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
41
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
42
+ */
43
+
44
+
45
+ 'use client';
46
+
47
+ // โš›๏ธ React
48
+ import { useCallback, useEffect, useId, useRef, useState, type CSSProperties, type ReactElement, type ReactNode } from 'react';
49
+ // ๐ŸŒ€ portal into the scope's drawer layer
50
+ import { createPortal } from 'react-dom';
51
+ // ๐Ÿงต classes
52
+ import clsx from 'clsx';
53
+ // ๐ŸŽจ styles
54
+ import styles from './styles.module.css';
55
+ // ๐ŸŽฌ motion classes (ab-nextjs-animations >= 0.2.4): the slide + the scrim fade, reduced motion included
56
+ import { AB_MOTION } from 'ab-nextjs-animations/motion';
57
+ import 'ab-nextjs-animations/motion/styles.css';
58
+ // ๐ŸŽ›๏ธ the controller hook + scope type
59
+ import { useAbDrawer, type AbDrawerScope, type UseAbDrawer } from './use-ab-drawer';
60
+
61
+ // ๐Ÿ“ฆ re-exports: one import for the whole drawer API
62
+ export { useAbDrawer };
63
+ export type { AbDrawerScope, UseAbDrawer };
64
+
65
+ /** ๐Ÿงญ where it slides in from. `start` / `end` follow the writing direction (RTL-aware). */
66
+ export type AbDrawerSide = 'top' | 'bottom' | 'left' | 'right' | 'start' | 'end';
67
+
68
+ /** โš™๏ธ props */
69
+ export interface AbDrawerProps {
70
+ open: boolean; // ๐Ÿšช controlled
71
+ onClose: () => void; // โŽ‹ Escape, scrim click and the close button call it
72
+ scope?: AbDrawerScope; // ๐Ÿ—บ๏ธ which box clips it (default `app`)
73
+ side?: AbDrawerSide; // ๐Ÿงญ default `bottom`
74
+ title?: ReactNode; // ๐Ÿท๏ธ a string becomes the `<h2>` that labels the dialog
75
+ 'aria-labelledby'?: string; // โ™ฟ your own visible title id (wins over `title`)
76
+ 'aria-label'?: string; // โ™ฟ when there is no visible title
77
+ id?: string; // ๐Ÿ†” the dialog id (`aria-controls` target)
78
+ children?: ReactNode; // ๐Ÿ“„ the body (it scrolls on its own)
79
+ footer?: ReactNode; // ๐Ÿ”š actions row (stays put)
80
+ size?: string; // ๐Ÿ“ width (start/end/left/right) or height (top/bottom), e.g. `360px`
81
+ modal?: boolean; // ๐Ÿ”’ trap focus + make the rest of the scope inert (default `true`)
82
+ closeLabel?: string; // ๐ŸŒ default "Close"
83
+ noJsFallback?: boolean; // ๐Ÿงฉ D41: without JS, render the content in flow (default `true`)
84
+ initialFocus?: 'first' | 'panel'; // ๐ŸŽฏ on open: the first control (default) or the panel itself (no ring on the โœ•; Tab then enters)
85
+ className?: string; // ๐Ÿท๏ธ
86
+ }
87
+
88
+ /** โฑ๏ธ the slide, same as the panes aside (core 0.1.6) */
89
+ export const AB_DRAWER_DURATION = 240;
90
+
91
+ // ๐Ÿ”Ž the element each scope is clipped by (core 0.1.6 data-ab-part hooks)
92
+ const SCOPE_SELECTOR: Record<AbDrawerScope, string> = {
93
+ app: '.AbAppLayout', // ๐Ÿ  the whole app box
94
+ main: '[data-ab-part="main"]', // ๐Ÿ“„ the main pane (not its scroller, so the drawer doesn't scroll away)
95
+ aside: '[data-ab-part="aside"]', // ๐Ÿ“‘ the aside pane
96
+ };
97
+
98
+ /**
99
+ * ๐Ÿ—บ๏ธ getAbDrawerHost โ€” the box a drawer of `scope` is clipped by: the scope element that contains `from`
100
+ * (so two layouts on a page each get their own), else the first one in the document, else `<body>`.
101
+ * Effects / handlers only (it reads the DOM).
102
+ */
103
+ export function getAbDrawerHost(scope: AbDrawerScope, from?: Element | null): HTMLElement {
104
+ const sel = SCOPE_SELECTOR[scope]; // ๐Ÿ”Ž
105
+ return from?.closest<HTMLElement>(sel) ?? document.querySelector<HTMLElement>(sel) ?? document.body; // ๐ŸŽฏ
106
+ }
107
+
108
+ // โ™ฟ everything that can take focus inside the panel
109
+ const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
110
+
111
+ // ๐Ÿ“ hosts with a drawer layer, ref-counted: `data-ab-drawer-host` stays while ANY drawer still uses the box.
112
+ // CSS (`:where([data-ab-drawer-host])`, zero specificity) gives a static host `position: relative`; no inline
113
+ // styles are written. A core rule on its layout boxes could replace this later.
114
+ const hostCount = new WeakMap<HTMLElement, number>();
115
+ const holdHost = (host: HTMLElement) => { const n = (hostCount.get(host) ?? 0) + 1; hostCount.set(host, n); host.setAttribute('data-ab-drawer-host', ''); };
116
+ const releaseHost = (host: HTMLElement) => {
117
+ const n = (hostCount.get(host) ?? 1) - 1;
118
+ if (n > 0) { hostCount.set(host, n); return; }
119
+ hostCount.delete(host); host.removeAttribute('data-ab-drawer-host'); // ๐Ÿงน last one out
120
+ };
121
+
122
+ // ๐Ÿฅž open drawers, newest last: only the top one answers Escape / Tab (a drawer opened from a drawer)
123
+ const openStack: symbol[] = [];
124
+ /** ๐Ÿฅž is `token` the topmost open drawer? */
125
+ const isTopDrawer = (token: symbol): boolean => openStack[openStack.length - 1] === token;
126
+
127
+ // โ™ฟ reduced-motion check, read once per open / close on purpose: it only picks the unmount delay for THAT
128
+ // toggle (the slide itself is CSS, which follows the media query live), so a listener would buy nothing
129
+ const reducedMotion = (): boolean => typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
130
+
131
+ /**
132
+ * ๐Ÿ—„๏ธ AbDrawer (G53) โ€” a panel that slides in from any side, clipped by its **scope** (app / main / aside).
133
+ *
134
+ * - ๐Ÿ“ Rendered into an absolute `inset: 0` layer INSIDE the scope box, so it never makes the document scroll
135
+ * (the D34 rule); its body is its own scroller (`overscroll-behavior: contain`).
136
+ * - โ™ฟ `role="dialog"` + `aria-modal`, labelled by `title` / `aria-labelledby`; focus moves in on open, is
137
+ * trapped (Tab / Shift+Tab), and returns to the opener on close; Escape and a scrim click close it;
138
+ * the rest of the scope is `inert` while it's open (only the scope, unless `scope="app"`).
139
+ * - ๐ŸŽž๏ธ 240ms slide; no motion and instant open/close under `prefers-reduced-motion`.
140
+ * - ๐Ÿงฑ Scopes need **ab-nextjs-core 0.1.6+** markup (`.AbAppLayout`, `[data-ab-part="main"]`, `[data-ab-part="aside"]`);
141
+ * with older core (or no layout) it falls back to a viewport layer on `<body>`.
142
+ * - ๐Ÿงฉ D41 no-JS: the server renders the content as an in-flow `<section>` (hidden as soon as scripting runs).
143
+ */
144
+ const AbDrawer = (props: AbDrawerProps): ReactElement => {
145
+ const { open, onClose, scope = 'app', side = 'bottom', title, id, children, footer, size, modal = true, closeLabel = 'Close', noJsFallback = true, initialFocus = 'first', className } = props;
146
+ const auto = useId().replace(/[^A-Za-z0-9_-]/g, ''); // ๐Ÿ†” SSR-stable
147
+ const dialogId = id ?? `ab-drawer-${auto}`; // ๐Ÿ†”
148
+ const titleId = `${dialogId}-title`; // ๐Ÿท๏ธ
149
+ const labelledBy = props['aria-labelledby'] ?? (title != null ? titleId : undefined); // โ™ฟ
150
+ const anchor = useRef<HTMLDivElement>(null); // ๐Ÿ“ where we are in the tree (picks the right layout)
151
+ const panel = useRef<HTMLDivElement>(null); // ๐Ÿ—„๏ธ
152
+ const opener = useRef<Element | null>(null); // โ†ฉ๏ธ focus goes back here
153
+ const close = useRef(onClose); // ๐Ÿ” latest onClose for the listeners
154
+ useEffect(() => { close.current = onClose; }, [onClose]); // ๐Ÿ” synced after render, never during
155
+
156
+ // ๐Ÿงญ client-only state: the layer we portal into, whether the panel is in the DOM, whether it's slid in
157
+ const [layer, setLayer] = useState<HTMLElement | null>(null);
158
+ const [present, setPresent] = useState(open); // ๐Ÿงฑ mounted (open, or sliding out)
159
+ const [shown, setShown] = useState(false); // ๐ŸŽž๏ธ slid in
160
+ const [token] = useState(() => Symbol('ab-drawer')); // ๐Ÿฅž our place in the open stack
161
+
162
+ // ๐Ÿ—บ๏ธ find the scope box once we're on the client and make a layer in it
163
+ useEffect(() => {
164
+ const host = getAbDrawerHost(scope, anchor.current); // ๐ŸŽฏ
165
+ const el = document.createElement('div'); // ๐Ÿงฑ one layer per drawer (no shared state to clean up)
166
+ el.setAttribute('data-ab-drawer-layer', scope);
167
+ el.className = clsx('AbDrawerLayer', styles.abDrawerLayer);
168
+ if (host === document.body) el.setAttribute('data-host', 'body'); // ๐Ÿ“Œ no layout: cover the viewport
169
+ host.appendChild(el);
170
+ // eslint-disable-next-line react-hooks/set-state-in-effect -- ๐ŸŒ€ the layer is external DOM that only exists after mount (SSR keeps the in-flow fallback); one extra render on hydration is the point
171
+ setLayer(el);
172
+ return () => { el.remove(); setLayer(null); }; // ๐Ÿงน
173
+ }, [scope]);
174
+
175
+ // ๐Ÿ“ hold the host (position context) while the panel is in the DOM (open or sliding out)
176
+ useEffect(() => {
177
+ const host = layer?.parentElement;
178
+ if (!present || !host || host === document.body) return; // ๐Ÿ“Œ body layer is fixed: no context needed
179
+ holdHost(host);
180
+ return () => releaseHost(host);
181
+ }, [present, layer]);
182
+
183
+ // ๐Ÿงฎ derived during render (React's "adjust state on prop change"): open mounts at once, close starts the slide out
184
+ if (open && !present) setPresent(true);
185
+ if (!open && shown) setShown(false);
186
+
187
+ // ๐ŸŽž๏ธ open โ†’ mount, then slide in on the next frame; close โ†’ slide out, then unmount
188
+ useEffect(() => {
189
+ const ms = reducedMotion() ? 0 : AB_DRAWER_DURATION; // โ™ฟ
190
+ if (open) {
191
+ const raf = requestAnimationFrame(() => requestAnimationFrame(() => setShown(true))); // ๐Ÿ› two frames: start state painted first
192
+ return () => cancelAnimationFrame(raf);
193
+ }
194
+ const t = window.setTimeout(() => setPresent(false), ms); // โฑ๏ธ one timer, so quick toggles never race
195
+ return () => window.clearTimeout(t);
196
+ }, [open]);
197
+
198
+ // โ†ฉ๏ธ remember the trigger the moment we open (before the scope turns inert and blurs it)
199
+ useEffect(() => { if (open && !panel.current?.contains(document.activeElement)) opener.current = document.activeElement; }, [open]);
200
+
201
+ // โ™ฟ focus in on open, back to the opener on close
202
+ useEffect(() => {
203
+ if (!open || !present || !panel.current) return;
204
+ const first = initialFocus === 'panel' ? null : panel.current.querySelector<HTMLElement>(FOCUSABLE); // ๐ŸŽฏ first control, else the panel
205
+ (first ?? panel.current).focus({ preventScroll: true });
206
+ return () => {
207
+ const back = opener.current as HTMLElement | null; // โ†ฉ๏ธ
208
+ // โญ๏ธ a microtask later: the inert cleanup below runs after this one, and an inert opener can't take focus
209
+ queueMicrotask(() => { if (back && back.isConnected && typeof back.focus === 'function') back.focus({ preventScroll: true }); });
210
+ };
211
+ }, [open, present, layer, initialFocus]); // ๐ŸŽฏ initialFocus is static in practice
212
+
213
+ // ๐Ÿ”’ the rest of the scope is inert while open (modal only); we only undo what we set
214
+ useEffect(() => {
215
+ if (!open || !modal || !layer?.parentElement) return;
216
+ const touched: HTMLElement[] = [];
217
+ for (const sib of Array.from(layer.parentElement.children) as HTMLElement[]) {
218
+ if (sib === layer || sib.hasAttribute('inert') || sib.hasAttribute('data-ab-drawer-layer')) continue; // ๐Ÿ™… ours / already inert / other drawers
219
+ sib.setAttribute('inert', ''); touched.push(sib); // ๐ŸงŠ
220
+ }
221
+ return () => { for (const el of touched) el.removeAttribute('inert'); }; // ๐Ÿ”“
222
+ }, [open, modal, layer]);
223
+
224
+ // ๐Ÿฅž join the open stack while open (StrictMode-safe: cleanup removes exactly us)
225
+ useEffect(() => {
226
+ if (!open) return;
227
+ openStack.push(token);
228
+ return () => { const i = openStack.lastIndexOf(token); if (i >= 0) openStack.splice(i, 1); };
229
+ }, [open, token]);
230
+
231
+ // โŽ‹ Escape closes (skips events an inner menu already handled); Tab stays inside (modal). Topmost drawer only
232
+ const onKeyDown = useCallback((e: KeyboardEvent) => {
233
+ if (!panel.current || !isTopDrawer(token)) return; // ๐Ÿฅž a drawer under another one stays put
234
+ if (e.key === 'Escape' && !e.defaultPrevented) { e.preventDefault(); close.current(); return; } // โŽ‹
235
+ if (e.key !== 'Tab' || !modal) return;
236
+ const items = Array.from(panel.current.querySelectorAll<HTMLElement>(FOCUSABLE)).filter((el) => el.getClientRects().length > 0 || el === document.activeElement); // ๐Ÿ‘€ rendered (keeps position: fixed, which has no offsetParent)
237
+ if (items.length === 0) { e.preventDefault(); panel.current.focus(); return; } // ๐Ÿ”’ nothing to tab to
238
+ const [a, z] = [items[0], items[items.length - 1]];
239
+ const inside = panel.current.contains(document.activeElement);
240
+ if (e.shiftKey && (document.activeElement === a || !inside)) { e.preventDefault(); z.focus(); } // โฌ…๏ธ wrap
241
+ else if (!e.shiftKey && (document.activeElement === z || !inside)) { e.preventDefault(); a.focus(); } // โžก๏ธ wrap
242
+ }, [modal, token]);
243
+ useEffect(() => {
244
+ if (!open) return;
245
+ document.addEventListener('keydown', onKeyDown); // ๐ŸŽง document-level, so Escape works wherever focus is
246
+ return () => document.removeEventListener('keydown', onKeyDown);
247
+ }, [open, onKeyDown]);
248
+
249
+ // ๐Ÿท๏ธ a plain-string title becomes the labelling heading
250
+ const heading = title == null ? null : typeof title === 'string' || typeof title === 'number'
251
+ ? <h2 id={titleId} className={styles.abDrawerTitle}>{title}</h2>
252
+ : <div id={props['aria-labelledby'] ? undefined : titleId} className={styles.abDrawerTitle}>{title}</div>;
253
+ const sizeVar = size ? ({ '--ab-drawer-size': size } as CSSProperties) : undefined; // ๐Ÿ“
254
+
255
+ // ๐Ÿงฉ D41: before hydration (and with no JS at all) the content is an in-flow section
256
+ if (!layer) {
257
+ return (
258
+ <div ref={anchor} className={styles.abDrawerAnchor} data-ab-part="drawer-anchor">
259
+ {noJsFallback ? (
260
+ <section className={clsx('AbDrawerFallback', styles.abDrawerFallback)} data-ab-part="drawer-fallback" aria-labelledby={labelledBy} aria-label={labelledBy ? undefined : props['aria-label']}>
261
+ {heading}
262
+ <div className={styles.abDrawerBody}>{children}</div>
263
+ {footer != null && <div className={styles.abDrawerFooter}>{footer}</div>}
264
+ </section>
265
+ ) : null}
266
+ </div>
267
+ );
268
+ }
269
+
270
+ return (
271
+ <div ref={anchor} className={styles.abDrawerAnchor} data-ab-part="drawer-anchor">
272
+ {present && createPortal(
273
+ <div className={styles.abDrawerFrame} data-state={shown ? 'open' : 'closed'} data-side={side} data-scope={scope}>
274
+ {/* ๐ŸŒซ๏ธ scrim: a click closes (pointer only; keyboard users have Escape and the close button) */}
275
+ <div className={clsx(styles.abDrawerScrim, AB_MOTION.colors)} data-ab-part="drawer-scrim" aria-hidden="true" onClick={() => close.current()} />
276
+ <div
277
+ ref={panel}
278
+ id={dialogId}
279
+ role="dialog"
280
+ aria-modal={modal ? 'true' : undefined}
281
+ aria-labelledby={labelledBy}
282
+ aria-label={labelledBy ? undefined : props['aria-label']}
283
+ tabIndex={-1} // ๐ŸŽฏ focus target when there are no controls
284
+ className={clsx('AbDrawer', styles.abDrawer, AB_MOTION.transform, className)}
285
+ data-ab-part="drawer"
286
+ data-side={side}
287
+ style={sizeVar}
288
+ >
289
+ <div className={styles.abDrawerHeader}>
290
+ {heading}
291
+ <button type="button" className={styles.abDrawerClose} data-ab-part="drawer-close" aria-label={closeLabel} onClick={() => close.current()}>
292
+ <span aria-hidden="true">โœ•</span>
293
+ </button>
294
+ </div>
295
+ <div className={styles.abDrawerBody} data-ab-part="drawer-body">{children}</div>
296
+ {footer != null && <div className={styles.abDrawerFooter} data-ab-part="drawer-footer">{footer}</div>}
297
+ </div>
298
+ </div>,
299
+ layer,
300
+ )}
301
+ </div>
302
+ );
303
+ };
304
+
305
+ // ๐Ÿ“ฆ exports
306
+ export default AbDrawer;
307
+ export { AbDrawer };