ab-nextjs-components 0.1.14 → 0.2.1

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 (40) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +5 -0
  3. package/ab-app-bar/index.tsx +17 -6
  4. package/ab-app-bar/styles.module.css +27 -2
  5. package/ab-balloon/index.tsx +35 -3
  6. package/ab-balloon/styles.module.css +8 -0
  7. package/ab-bottom-drawer/styles.module.css +1 -1
  8. package/ab-breadcrumbs/index.tsx +1 -1
  9. package/ab-drawer/gestures.ts +134 -0
  10. package/ab-drawer/index.tsx +168 -12
  11. package/ab-drawer/kit.module.css +210 -0
  12. package/ab-drawer/styles.module.css +39 -0
  13. package/ab-drawer/use-ab-edge-swipe.ts +165 -0
  14. package/ab-icon-button/index.tsx +1 -1
  15. package/ab-locale-switcher/index.tsx +64 -3
  16. package/ab-locale-switcher/styles.module.css +20 -0
  17. package/ab-mobile-header/index.tsx +100 -0
  18. package/ab-nav-drawer/index.tsx +158 -0
  19. package/ab-navbar/index.tsx +1 -1
  20. package/ab-package-card/index.tsx +2 -0
  21. package/ab-package-card/previews.tsx +94 -0
  22. package/ab-package-card/styles.module.css +21 -0
  23. package/ab-profile-avatar/index.tsx +105 -0
  24. package/ab-profile-avatar/styles.module.css +53 -0
  25. package/ab-search-drawer/index.tsx +279 -0
  26. package/ab-search-trigger/index.tsx +8 -3
  27. package/ab-search-trigger/styles.module.css +3 -0
  28. package/ab-settings-drawer/index.tsx +203 -0
  29. package/ab-sidebar/index.tsx +10 -2
  30. package/ab-sidebar/profile-button.tsx +115 -0
  31. package/ab-sidebar/styles.module.css +43 -0
  32. package/ab-sidebar/view.tsx +9 -1
  33. package/ab-toc/index.tsx +3 -0
  34. package/ab-toc/promo.tsx +74 -0
  35. package/ab-toc/styles.module.css +16 -0
  36. package/ab-toc-drawer/index.tsx +129 -0
  37. package/ab-version-switcher/index.tsx +5 -5
  38. package/index.ts +36 -1
  39. package/package.json +15 -3
  40. package/types/index.d.ts +27 -1
@@ -0,0 +1,165 @@
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: useAbEdgeSwipe
28
+ * @file: ab-drawer/use-ab-edge-swipe.ts
29
+ * @type: Client hook
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
33
+ /*
34
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35
+ * MOTTO: We'll always do more 😜!!!
36
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37
+ */
38
+
39
+ 'use client';
40
+
41
+ // ⚛️ React
42
+ import { useEffect, useRef } from 'react';
43
+ // 🤏 the pure rules
44
+ import { AB_SWIPE, createAbVelocityTracker, isInAbEdgeZone, isInAbHorizontalScroller, resolveAbSideRelease } from './gestures';
45
+ // 🗺️ the app box (same lookup AbDrawer uses)
46
+ import { getAbDrawerHost } from './index';
47
+
48
+ /** ⚙️ options */
49
+ export interface UseAbEdgeSwipeOptions {
50
+ edge: 'left' | 'right'; // 🧱 which edge the swipe starts from (left = left-to-right, opens the left drawer)
51
+ onOpen: () => void; // 🚪 called when the swipe commits
52
+ enabled?: boolean; // 🎚️ e.g. false while that drawer is open, or when the page has no aside (default true)
53
+ width?: number; // 📏 the drawer width the 30% rule uses (default 320)
54
+ pointerTypes?: readonly string[]; // 🖐️ default touch + pen (a mouse never edge-swipes)
55
+ // 📐 0.2.1 (God 02:47): only swipe while the viewport is at most this wide, e.g. AB_ASIDE_DRAWER_MAX_WIDTH (1179) for
56
+ // the right drawer: mobile AND tablet hide the aside and open it as the right drawer; from 1180px it's a column
57
+ maxWidth?: number;
58
+ }
59
+
60
+ /** 📐 0.2.1: the widest viewport where the aside is a right drawer (mobile + tablet; the column starts at 1180px) */
61
+ export const AB_ASIDE_DRAWER_MAX_WIDTH = 1179;
62
+
63
+ // 📱 iOS home-screen web app (the zone starts 16px in there)
64
+ const standalone = (): boolean => typeof navigator !== 'undefined' && (navigator as Navigator & { standalone?: boolean }).standalone === true;
65
+
66
+ /**
67
+ * 🤏 useAbEdgeSwipe — open a side drawer with an edge swipe (drawer spec §2 / §3):
68
+ * - 🧱 the press starts in a 24px zone on that edge of the app box (16px in on iOS standalone)
69
+ * - ↔️ it commits past 30% of the drawer width or above 0.5px/ms toward the middle; slower or shorter does nothing
70
+ * - 🎠 ignored inside things that scroll sideways (code blocks, carousels) and `[data-ab-no-edge-swipe]`
71
+ * - 🧭 a mostly vertical move is a scroll, not a swipe
72
+ * - 📱 iOS Safari's own back gesture starts at the very screen edge and takes the touch before the page sees it,
73
+ * so the two don't fight; in standalone mode the 16px inset leaves that edge to the system
74
+ *
75
+ * - 👆 touch uses touch events (non-passive touchmove only during an edge press, preventDefault only once it's
76
+ * sideways), so Android Chrome's pointercancel-on-pan can't swallow it
77
+ *
78
+ * The drawer opens on release (it doesn't follow the finger), then slides in with its normal 200ms motion.
79
+ */
80
+ export function useAbEdgeSwipe({ edge, onOpen, enabled = true, width = 320, pointerTypes = ['touch', 'pen'], maxWidth }: UseAbEdgeSwipeOptions): void {
81
+ const latest = useRef(onOpen); // 🔁 latest callback for the listener
82
+ useEffect(() => { latest.current = onOpen; }, [onOpen]);
83
+ const types = pointerTypes.join(','); // 🧮 a stable dep
84
+ useEffect(() => {
85
+ if (!enabled) return;
86
+ let d: { x: number; y: number; axis: 0 | 1 | 2; v: ReturnType<typeof createAbVelocityTracker> } | null = null; // 🫳 the current press
87
+ const sign = edge === 'left' ? 1 : -1; // ➡️ / ⬅️ toward the middle
88
+ const allow = types.split(','); // 🖐️
89
+ // 🧱 shared start rule (pointer or touch): from the edge zone, not in a sideways scroller / opt-out / open drawer
90
+ const start = (x: number, y: number, t: number, target: Element): boolean => {
91
+ if (maxWidth != null && window.innerWidth > maxWidth) return false; // 📐 0.2.1: too wide (e.g. the aside is a column)
92
+ const host = getAbDrawerHost('app', target); // 🗺️ the app box
93
+ const box = host === document.body ? { left: 0, right: window.innerWidth } : host.getBoundingClientRect();
94
+ if (!isInAbEdgeZone(x, edge, box, standalone())) return false; // 🧱 not from the edge
95
+ if (isInAbHorizontalScroller(target)) return false; // 🎠 (also [data-ab-no-edge-swipe])
96
+ if (target.closest?.('[data-ab-part="drawer"]')) return false; // 🗄️ a drawer is already up there
97
+ const v = createAbVelocityTracker(); v.add(x, t);
98
+ d = { x, y, axis: 0, v }; return true;
99
+ };
100
+ // 🧭 shared move rule; returns true while the gesture is ours (sideways)
101
+ const step = (x: number, y: number, t: number): boolean => {
102
+ if (!d || d.axis === 2) return false;
103
+ const dx = x - d.x; const dy = y - d.y;
104
+ if (d.axis === 0) {
105
+ if (Math.max(Math.abs(dx), Math.abs(dy)) < AB_SWIPE.slop) return false; // 🫳
106
+ d.axis = Math.abs(dx) > Math.abs(dy) ? 1 : 2; // 🧭 sideways = ours, vertical = the page's scroll
107
+ }
108
+ if (d.axis === 1) { d.v.add(x, t); return true; } // ⚡
109
+ return false;
110
+ };
111
+ const finish = (x: number) => {
112
+ const cur = d; d = null;
113
+ if (!cur || cur.axis !== 1) return;
114
+ if (resolveAbSideRelease({ distance: (x - cur.x) * sign, velocity: cur.v.velocity() * sign, width })) {
115
+ (document.activeElement as HTMLElement | null)?.blur?.(); // ↩️ 0.2.1 (Joseph): a swipe has no opener, so the drawer returns focus to the logo, not a stale element
116
+ latest.current(); // ✅
117
+ }
118
+ };
119
+
120
+ // 🖊️ pointer path: pen (and touch only where there are no touch events)
121
+ const touchy = typeof window !== 'undefined' && 'ontouchstart' in window;
122
+ const byPointer = (e: PointerEvent) => allow.includes(e.pointerType) && !(touchy && e.pointerType === 'touch');
123
+ const down = (e: PointerEvent) => { if (byPointer(e)) start(e.clientX, e.clientY, e.timeStamp, e.target as Element); };
124
+ const move = (e: PointerEvent) => { if (byPointer(e)) step(e.clientX, e.clientY, e.timeStamp); };
125
+ const up = (e: PointerEvent) => { if (byPointer(e)) finish(e.clientX); };
126
+ const cancel = (e: PointerEvent) => { if (byPointer(e)) d = null; }; // 🧹 the browser took it (scroll)
127
+
128
+ // 👆 touch path (Android Chrome fix): Chromium fires pointercancel as soon as it starts a native pan, so a
129
+ // touch swipe is read from touch events instead. A NON-passive touchmove listener is attached only while a
130
+ // touch that started in the edge zone is down (no scroll jank elsewhere), and it calls preventDefault only
131
+ // once the move is sideways. Vertical moves are never prevented, so the page still scrolls from the strip.
132
+ const tmove = (e: TouchEvent) => {
133
+ const t = e.touches[0]; if (!t) return;
134
+ if (step(t.clientX, t.clientY, e.timeStamp) && e.cancelable) e.preventDefault(); // 🛑 ours: keep the browser out
135
+ if (d?.axis === 2) detach(); // 🧭 a scroll: let go early
136
+ };
137
+ const tend = (e: TouchEvent) => { const t = e.changedTouches[0]; detach(); if (t && e.type === 'touchend') finish(t.clientX); else d = null; };
138
+ const attach = () => { document.addEventListener('touchmove', tmove, { capture: true, passive: false }); document.addEventListener('touchend', tend, true); document.addEventListener('touchcancel', tend, true); };
139
+ const detach = () => { document.removeEventListener('touchmove', tmove, true); document.removeEventListener('touchend', tend, true); document.removeEventListener('touchcancel', tend, true); };
140
+ const tstart = (e: TouchEvent) => {
141
+ if (!allow.includes('touch')) return;
142
+ detach(); d = null;
143
+ if (e.touches.length !== 1) return; // ✌️ pinch etc. are not swipes
144
+ const t = e.touches[0];
145
+ if (start(t.clientX, t.clientY, e.timeStamp, e.target as Element)) attach();
146
+ };
147
+
148
+ document.addEventListener('pointerdown', down, true); // 🎧 capture: before anything stops it
149
+ document.addEventListener('pointermove', move, true);
150
+ document.addEventListener('pointerup', up, true);
151
+ document.addEventListener('pointercancel', cancel, true);
152
+ document.addEventListener('touchstart', tstart, { capture: true, passive: true }); // 👆 passive: never delays a tap or scroll
153
+ return () => {
154
+ document.removeEventListener('pointerdown', down, true);
155
+ document.removeEventListener('pointermove', move, true);
156
+ document.removeEventListener('pointerup', up, true);
157
+ document.removeEventListener('pointercancel', cancel, true);
158
+ document.removeEventListener('touchstart', tstart, true);
159
+ detach();
160
+ };
161
+ }, [edge, enabled, width, types, maxWidth]);
162
+ }
163
+
164
+ // 📦 default export
165
+ export default useAbEdgeSwipe;
@@ -31,7 +31,7 @@
31
31
  *
32
32
  * Example usage:
33
33
  * 1+|> <AbIconButton icon="arrow_back" label={t('back')} onClick={prev} />
34
- * -|> <AbIconButton icon="open_in_new" href="/docs" label="Open docs" /> // 🔗 link variant is named too
34
+ * -|> <AbIconButton icon="open_in_new" href="/packages" label="Open packages" /> // 🔗 link variant is named too
35
35
  */
36
36
 
37
37
  /*
@@ -32,6 +32,19 @@
32
32
  * Example usage:
33
33
  * 1+|> const { switchLocale } = useAbLocaleSwitch() // 🌍 from ab-nextjs-i18n/navigation
34
34
  * -|> <AbLocaleSwitcher label={t('language')} current={locale} locales={[{ code: 'en', label: 'English' }, { code: 'fr', label: 'Français' }]} onSelect={switchLocale} />
35
+ *
36
+ * 🧩 0.1.15 inline, inside the mobile app drawer (John):
37
+ * 2+|> // a) mixed drawer: nav + theme first, LANGUAGE last under a 1px rule
38
+ * -|> <AbBottomDrawer open={open} onClose={close} title={t('menu')}>
39
+ * -|> <AbDrawerList … />{themeRow}
40
+ * -|> <AbLocaleSwitcher presentation="inline" divider label={t('language')} current={locale} locales={LOCALES} onSelect={switchLocale} />
41
+ * -|> </AbBottomDrawer>
42
+ * 🔁 Switching `presentation` at runtime (e.g. inline in the drawer, menu on desktop) is safe: inline and popover
43
+ * are separate components, so React remounts instead of reordering hooks. `AbLocaleSwitcherInline` is also exported.
44
+ * 3+|> // b) language only: the drawer title says it, so no uppercase label
45
+ * -|> <AbBottomDrawer open={open} onClose={close} title={t('language')}>
46
+ * -|> <AbLocaleSwitcher presentation="inline" showLabel={false} label={t('language')} current={locale} locales={LOCALES} onSelect={switchLocale} />
47
+ * -|> </AbBottomDrawer>
35
48
  */
36
49
 
37
50
  /*
@@ -80,8 +93,17 @@ export interface AbLocaleSwitcherProps {
80
93
  icon?: ReactNode; // 🖼️ override the globe
81
94
  className?: string; // 🏷️
82
95
  style?: CSSProperties; // 🎨
83
- /** 🗄️ 0.1.14 (G56, D40): `menu` (default) = popover menu; `drawer` = AbDrawerList; `auto` = drawer below 768px, menu above */
84
- presentation?: AbPresentation;
96
+ /** 🗄️ 0.1.14 (G56, D40): `menu` (default) = popover menu; `drawer` = AbDrawerList; `auto` = drawer below 768px, menu above.
97
+ * 🧩 0.1.15 (God 00:08): `inline` = no trigger; a labelled list of rows rendered in place, e.g. inside the app drawer on mobile */
98
+ presentation?: AbPresentation | 'inline';
99
+ /** 🏷️ 0.1.15 (John): inline only. Show the small uppercase group label (default true). Set false when the language
100
+ * list is the drawer's only content and the drawer title already says "Language" (the label stays the group's name) */
101
+ showLabel?: boolean;
102
+ /** ♿ 0.1.15 (God 00:37): inline only. The group's accessible name. Default: `label` (e.g. "Language"), so a visible
103
+ * label and the name always agree; set it when the drawer needs a fuller name (e.g. "Choose a language") */
104
+ ariaLabel?: string;
105
+ /** ➖ 0.1.15 (John): inline only. A 1px --div rule above the block, for when it follows nav / theme items (default false) */
106
+ divider?: boolean;
85
107
  drawerScope?: AbDrawerScope; // 🗺️ default 'app'
86
108
  drawerSide?: 'top' | 'bottom' | 'start' | 'end'; // 🧭 default 'bottom'
87
109
  }
@@ -99,9 +121,48 @@ export function getAbTypeaheadIndex(labels: readonly string[], from: number, cha
99
121
  return -1; // 🙅
100
122
  }
101
123
 
124
+ /**
125
+ * 🧩 0.1.15: the inline list (no trigger, no popover), e.g. inside the mobile app drawer.
126
+ * Its own component (James): AbLocaleSwitcher picks this OR the popover by type, so switching `presentation`
127
+ * at runtime remounts instead of changing the hook order. Links mark the active row with aria-current, buttons aria-pressed.
128
+ */
129
+ export function AbLocaleSwitcherInline(props: AbLocaleSwitcherProps) {
130
+ const { locales, current, label, onSelect, getHref, className, style, showLabel = true, divider = false, ariaLabel } = props;
131
+ const base = useId(); // 🆔
132
+ return (
133
+ <div className={clsx('AbLocaleSwitcher', styles.inline, className)} style={style} data-ab-part="locale-switcher" data-presentation="inline" data-divider={divider ? 'true' : undefined} role="group" aria-labelledby={showLabel && ariaLabel == null ? `${base}-label` : undefined} aria-label={ariaLabel ?? (showLabel ? undefined : label)}>
134
+ {showLabel && <div id={`${base}-label`} className={styles.inlineLabel}>{label}</div> /* 🏷️ hidden when the drawer title says it */}
135
+ <ul className={styles.inlineList}>
136
+ {locales.map((l) => {
137
+ const on = l.code === current; // ✅
138
+ const inner = (<><span className={styles.inlineText}>{l.label}</span><span className={styles.inlineCheck} aria-hidden="true">{on ? <svg viewBox="0 0 18 18" width="18" height="18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" data-ab-part="locale-check"><path d="M3.5 9.5 7.25 13 14.5 5.5" /></svg> : null}</span></>);
139
+ return (
140
+ <li key={l.code}>
141
+ {getHref ? (
142
+ <a className={styles.inlineItem} href={getHref(l.code)} hrefLang={l.code} lang={l.code} data-active={on ? 'true' : 'false'} aria-current={on ? 'true' : undefined} onClick={() => onSelect?.(l.code)}>{inner}</a>
143
+ ) : (
144
+ <button type="button" className={styles.inlineItem} lang={l.code} data-active={on ? 'true' : 'false'} aria-pressed={on} onClick={() => onSelect?.(l.code)}>{inner}</button>
145
+ )}
146
+ </li>
147
+ );
148
+ })}
149
+ </ul>
150
+ </div>
151
+ );
152
+ }
153
+
154
+ /**
155
+ * 🌍 AbLocaleSwitcher: `presentation="inline"` renders AbLocaleSwitcherInline, anything else the popover / drawer.
156
+ * 🔁 Two component types, so a runtime `presentation` change remounts cleanly (rules of hooks).
157
+ */
102
158
  export function AbLocaleSwitcher(props: AbLocaleSwitcherProps) {
159
+ return props.presentation === 'inline' ? <AbLocaleSwitcherInline {...props} /> : <AbLocaleSwitcherPopover {...props} />;
160
+ }
161
+
162
+ function AbLocaleSwitcherPopover(props: AbLocaleSwitcherProps) {
103
163
  // 🧩 props
104
- const { locales, current, label, onSelect, getHref, variant = 'icon', align = 'end', icon, className, style, presentation = 'menu', drawerScope = 'app', drawerSide = 'bottom' } = props;
164
+ const { locales, current, label, onSelect, getHref, variant = 'icon', align = 'end', icon, className, style, presentation: rawPresentation = 'menu', drawerScope = 'app', drawerSide = 'bottom' } = props;
165
+ const presentation: AbPresentation = rawPresentation === 'inline' ? 'menu' : rawPresentation; // 🗄️ (never 'inline' here: see the dispatcher)
105
166
  // 🗄️ how this open happens (decided on click)
106
167
  const [mode, setMode] = useState<'menu' | 'drawer'>(presentation === 'drawer' ? 'drawer' : 'menu');
107
168
  // 🚪 open?
@@ -136,3 +136,23 @@
136
136
  .root > .menu { display: none; } /* 🙈 needs JS */
137
137
  .noJs { display: block; } /* 👁️ */
138
138
  }
139
+
140
+ /* ===== 🧩 0.1.15 (God 00:08): presentation="inline", the language list inside the mobile app drawer =====
141
+ * Rows match AbDrawerList / the Home drawer: 48px, 12px padding, radius 8, --tint + --accent-text + 650 when active. */
142
+ .inline { display: grid; gap: 4px; } /* 📐 */
143
+ .inlineLabel { padding: 14px 12px 6px; font-size: 11px; font-weight: 700; line-height: 15px; letter-spacing: 0.06em; text-transform: uppercase; color: var(--ab-color-faint, #807062); } /* 🏷️ = sidebar group label */
144
+ .inlineList { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; } /* 📜 John: 8px between rows */
145
+ .inlineList > li { display: block; margin: 0; padding: 0; line-height: 0; } /* 🧹 no inherited li spacing / line box: the row is the box */
146
+ .inlineItem {
147
+ display: flex; align-items: center; gap: 12px; box-sizing: border-box; inline-size: 100%; block-size: 48px; min-block-size: 44px; /* 👆 John: exactly 48px (≥ 44px hit area) */
148
+ padding: 8px 12px; border: 0; border-radius: var(--ab-radius-row, 8px); background: none; /* 🧹 */
149
+ font: inherit; font-size: 16px; line-height: 20px; text-align: start; color: var(--ab-color-text, #211a16); text-decoration: none; cursor: pointer; /* 🔤 */
150
+ }
151
+ .inlineItem:hover { background: var(--ab-color-hover, rgb(166 124 82 / 0.08)); } /* 🖱️ */
152
+ .inlineItem[data-active='true'] { background: var(--ab-color-tint, #f4e7db); color: var(--ab-color-accent-text, #88603d); font-weight: 650; } /* 🎯 */
153
+ .inlineItem:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: -2px; } /* ♿ */
154
+ .inlineText { flex: 1 1 auto; min-width: 0; } /* 🏷️ */
155
+ .inlineCheck { flex: none; display: inline-flex; inline-size: 18px; block-size: 18px; color: var(--ab-locale-check-color, var(--ab-color-btn, #8b6340)); } /* ✓ John: bronze 2px stroke, 18px (James P2: the --ab-color-btn token) */
156
+ :global(.dark) .inlineCheck, :global([data-theme='dark']) .inlineCheck { color: var(--ab-locale-check-color, var(--ab-color-accent, #c29a6f)); } /* 🌙 the warm accent */
157
+ /* ➖ 0.1.15 (John): language goes LAST in a drawer with nav / theme items, under a 1px --div rule */
158
+ .inline[data-divider='true'] { margin-top: 8px; padding-top: 8px; border-top: 1px solid var(--ab-color-div, rgb(92 64 48 / 0.11)); }
@@ -0,0 +1,100 @@
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: AbMobileHeader
28
+ * @file: ab-mobile-header/index.tsx
29
+ * @type: Client component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * 1+|> <AbAppLayout variant="panes" mobileHeader="main" content={<AbMainLayout
34
+ * -|> mainHeader={<AbMobileHeader logo={<a href="/" id="home-logo">…</a>} onLanguage={openLanguage}
35
+ * -|> theme={mode} onThemeChange={setMode} />} … />} />
36
+ *
37
+ * 📌 Requires ab-nextjs-core ≥ 0.2.1 with `mobileHeader="main"` on AbAppLayout. That hides the app header below
38
+ * 768px and turns the main header slot into this 56px bar; older core shows it inside the normal main header.
39
+ */
40
+
41
+ /*
42
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
43
+ * MOTTO: We'll always do more 😜!!!
44
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
45
+ */
46
+
47
+
48
+ 'use client';
49
+
50
+ // ⚛️ React
51
+ import type { ReactElement, ReactNode } from 'react';
52
+ // 🧵 classes
53
+ import clsx from 'clsx';
54
+ // 🔣 icons
55
+ import AbIcon from '../ab-icon';
56
+ // 🎨 the drawers v2 kit
57
+ import kit from '../ab-drawer/kit.module.css';
58
+
59
+ /** ⚙️ props */
60
+ export interface AbMobileHeaderProps {
61
+ logo: ReactNode; // 🏷️ the logoname (22px), usually a link home: the focus target after a swipe-opened drawer closes
62
+ onLanguage?: () => void; // 🌍 the globe: open the Settings sheet with the language list in view
63
+ theme?: 'light' | 'dark'; // 🌗 the resolved theme now
64
+ onThemeChange?: (next: 'light' | 'dark') => void; // 🌗 the toggle (it shows the mode it switches TO: a moon in light)
65
+ actions?: ReactNode; // ➕ more 44px buttons after the two (none in John's frame)
66
+ labels?: { language?: string; toDark?: string; toLight?: string; header?: string }; // 🌍 "Change language", "Switch to dark theme", "Switch to light theme", "Main header"
67
+ languageExpanded?: boolean; // ♿ aria-expanded on the globe while its sheet is open
68
+ className?: string; // 🏷️
69
+ }
70
+
71
+ /**
72
+ * 📱 AbMobileHeader — John's mobile main header (drawers v2): logo left; a globe ("Change language",
73
+ * `aria-haspopup="dialog"`) and a theme toggle right, each 44×44. No search (the bottom nav has a Search tab) and
74
+ * no menu button (the left drawer opens with an edge swipe). Put it in AbMainLayout's `mainHeader` with core
75
+ * ≥ 0.2.1 `mobileHeader="main"`: the 56px row, its divider and the hidden app header come from core.
76
+ */
77
+ const AbMobileHeader = ({ logo, onLanguage, theme = 'light', onThemeChange, actions, labels = {}, languageExpanded, className }: AbMobileHeaderProps): ReactElement => {
78
+ const L = { language: 'Change language', toDark: 'Switch to dark theme', toLight: 'Switch to light theme', header: 'Main header', ...labels }; // 🌍
79
+ const next = theme === 'dark' ? 'light' : 'dark'; // 🌗 the target
80
+ return (
81
+ <div className={clsx('AbMobileHeader', kit.mh, className)} role="group" aria-label={L.header} data-ab-part="mobile-header">
82
+ <span className={kit.logoRow}>{logo}</span>
83
+ {onLanguage && (
84
+ <button type="button" className={kit.ibtn} aria-label={L.language} aria-haspopup="dialog" aria-expanded={languageExpanded} onClick={onLanguage} data-ab-part="mobile-header-language">
85
+ <AbIcon name="language" size={24} />
86
+ </button>
87
+ )}
88
+ {onThemeChange && (
89
+ <button type="button" className={kit.ibtn} aria-label={next === 'dark' ? L.toDark : L.toLight} onClick={() => onThemeChange(next)} data-ab-part="mobile-header-theme">
90
+ <AbIcon name={next === 'dark' ? 'dark_mode' : 'light_mode'} size={24} />
91
+ </button>
92
+ )}
93
+ {actions}
94
+ </div>
95
+ );
96
+ };
97
+
98
+ // 📦 exports
99
+ export default AbMobileHeader;
100
+ export { AbMobileHeader };
@@ -0,0 +1,158 @@
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: AbNavDrawer
28
+ * @file: ab-nav-drawer/index.tsx
29
+ * @type: Client component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * 1+|> useAbEdgeSwipe({ edge: 'left', onOpen: () => setNav(true), enabled: !nav })
34
+ * -|> <AbNavDrawer open={nav} onClose={() => setNav(false)} logo={<AbLogo />} version="v0.2.x"
35
+ * -|> sections={[{ id: 'top', items: [{ href: '/', label: 'Home', icon: 'home' }] }]} activeHref="/"
36
+ * -|> footer={[{ href: '/changelog', label: 'Changelog', icon: 'history' }]} onSettings={openSettings} />
37
+ */
38
+
39
+ /*
40
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
41
+ * MOTTO: We'll always do more 😜!!!
42
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
43
+ */
44
+
45
+
46
+ 'use client';
47
+
48
+ // ⚛️ React
49
+ import type { MouseEvent, ReactElement, ReactNode } from 'react';
50
+ // 🧵 classes
51
+ import clsx from 'clsx';
52
+ // 🗄️ the drawer
53
+ import AbDrawer from '../ab-drawer';
54
+ // 🔣 icons
55
+ import AbIcon from '../ab-icon';
56
+ // 🔗 the app's link (AbLinkProvider: next/link, or a locale-aware one)
57
+ import Link from '../ab-link';
58
+ // 🎯 the same active rule as the laptop sidebar
59
+ import { isAbSidebarActive } from '../ab-sidebar/view';
60
+ // 🎨 the drawers v2 kit
61
+ import kit from '../ab-drawer/kit.module.css';
62
+
63
+ /** 🔗 one nav row */
64
+ export interface AbNavDrawerItem {
65
+ href: string; // 🔗
66
+ label: string; // 🏷️
67
+ icon?: string; // 🔣 an AbIcons name
68
+ meta?: string; // 🏷️ trailing mono text, e.g. a version
69
+ }
70
+ /** 🗂️ one group: an optional uppercase label (a heading for its list) + rows */
71
+ export interface AbNavDrawerSection { id: string; label?: string; items: readonly AbNavDrawerItem[] }
72
+
73
+ /** ⚙️ props */
74
+ export interface AbNavDrawerProps {
75
+ open: boolean; // 🚪
76
+ onClose: () => void; // ⎋ scrim, Esc, ✕, a swipe back, or choosing a link
77
+ logo: ReactNode; // 🏷️ the logoname (a link home, usually)
78
+ version?: ReactNode; // 🏷️ a string = the mono version chip ("v0.2.x ⌄"); or your own picker node
79
+ onVersionClick?: () => void; // 🔽 the chip as a button (e.g. open a version menu)
80
+ sections: readonly AbNavDrawerSection[]; // 🗂️ same content as the laptop sidebar
81
+ activeHref?: string; // 🎯 exact match or parent prefix ("/" only matches itself)
82
+ footer?: readonly AbNavDrawerItem[]; // 📌 pinned 48px rows (e.g. Changelog)
83
+ onSettings?: () => void; // ⚙️ adds a "Settings ›" row; close this drawer, then open the Settings sheet
84
+ onNavigate?: (href: string) => void; // 🔔 after a link is chosen (the drawer closes either way)
85
+ labels?: { title?: string; close?: string; settings?: string; version?: string }; // 🌍 "Site navigation", "Close navigation", "Settings", "Version"
86
+ returnFocus?: string; // ↩️ e.g. the main header logo link (where focus goes after a swipe-open)
87
+ id?: string; // 🆔
88
+ className?: string; // 🏷️
89
+ }
90
+
91
+ /**
92
+ * ⬅️ AbNavDrawer — John's left drawer (drawers v2 §2): the mobile sidebar.
93
+ *
94
+ * - 📐 320px, full height, 0 16 16 0 radius; header = logo + 44px ✕; the version chip; a scrolling nav
95
+ * (44px rows, uppercase group headings, a 72px fade); a pinned footer of 48px rows
96
+ * - 🤏 opens with `useAbEdgeSwipe({ edge: 'left' })`; closes with a right-to-left swipe on the sheet (AbDrawer `swipe`),
97
+ * the scrim, Esc, ✕, or choosing a link
98
+ * - ♿ `role="dialog"` + aria-modal, aria-label "Site navigation"; `aria-current="page"` on the active row; each
99
+ * group label is a heading that labels its list
100
+ * - 🥞 tier 'nav': in front of the right drawer, under the bottom sheet
101
+ */
102
+ const AbNavDrawer = ({ open, onClose, logo, version, onVersionClick, sections, activeHref, footer = [], onSettings, onNavigate, labels = {}, returnFocus, id = 'ab-nav-drawer', className }: AbNavDrawerProps): ReactElement => {
103
+ const L = { title: 'Site navigation', close: 'Close navigation', settings: 'Settings', version: 'Version', ...labels }; // 🌍
104
+ const choose = (href: string) => (e: MouseEvent) => { if (e.defaultPrevented) return; onNavigate?.(href); onClose(); }; // 🔗 then close
105
+ const row = (it: AbNavDrawerItem, cls: string) => {
106
+ const on = isAbSidebarActive(it.href, activeHref); // 🎯
107
+ return (
108
+ <Link href={it.href} className={cls} aria-current={on ? 'page' : undefined} onClick={choose(it.href)}>
109
+ {it.icon && <AbIcon name={it.icon} filled={on} size={cls === kit.row ? 24 : 22} />}
110
+ <span>{it.label}</span>
111
+ {it.meta && <span className={kit.mini}>{it.meta}</span>}
112
+ </Link>
113
+ );
114
+ };
115
+ // 🏷️ a string version = the mock chip (mono, accent), optionally a button
116
+ const chip = typeof version === 'string'
117
+ ? (onVersionClick
118
+ ? <button type="button" className={kit.ver} aria-label={`${L.version} ${version}`} aria-haspopup="menu" onClick={onVersionClick}><b>{version}</b><AbIcon name="expand_more" size={18} /></button>
119
+ : <span className={kit.ver} aria-label={`${L.version} ${version}`}><b>{version}</b><AbIcon name="expand_more" size={18} /></span>)
120
+ : version;
121
+ return (
122
+ <AbDrawer
123
+ open={open} onClose={onClose} id={id} side="left" scope="app" tier="nav" swipe size="320px"
124
+ headerStart={<span className={kit.logoRow}>{logo}</span>} aria-label={L.title}
125
+ closeLabel={L.close} closeIcon={<AbIcon name="close" size={24} />} initialFocus="panel" returnFocus={returnFocus}
126
+ className={clsx('AbNavDrawer', kit.sheet, className)}
127
+ >
128
+ {chip != null && <div className={kit.verRow}>{chip}</div>}
129
+ <div className={kit.navWrap}>
130
+ <nav className={kit.nav} aria-label={L.title} data-ab-part="nav-drawer-nav">
131
+ {sections.map((s) => (
132
+ <div key={s.id} role="group" aria-labelledby={s.label ? `${id}-${s.id}` : undefined}>
133
+ {s.label && <h3 id={`${id}-${s.id}`} className={kit.grp}>{s.label}</h3>}
134
+ <ul className={kit.list} aria-labelledby={s.label ? `${id}-${s.id}` : undefined}>
135
+ {s.items.map((it) => <li key={it.href}>{row(it, kit.nv)}</li>)}
136
+ </ul>
137
+ </div>
138
+ ))}
139
+ </nav>
140
+ <div className={kit.fade} aria-hidden="true" />
141
+ </div>
142
+ {(footer.length > 0 || onSettings) && (
143
+ <div className={kit.navFoot} data-ab-part="nav-drawer-footer">
144
+ {footer.map((it) => <div key={it.href}>{row(it, kit.row)}</div>)}
145
+ {onSettings && (
146
+ <button type="button" className={kit.row} aria-haspopup="dialog" onClick={() => { onClose(); onSettings(); }}>
147
+ <AbIcon name="settings" size={24} /><span>{L.settings}</span><AbIcon name="chevron_right" size={24} className={kit.chev} />
148
+ </button>
149
+ )}
150
+ </div>
151
+ )}
152
+ </AbDrawer>
153
+ );
154
+ };
155
+
156
+ // 📦 exports
157
+ export default AbNavDrawer;
158
+ export { AbNavDrawer };
@@ -30,7 +30,7 @@
30
30
  * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
31
  *
32
32
  * Example usage:
33
- * <AbNavbar activeHref="/docs" items={[
33
+ * <AbNavbar activeHref="/" items={[
34
34
  * { kind: 'link', href: '/', icon: 'home', label: 'Home' },
35
35
  * { kind: 'button', id: 'menu', icon: 'menu', label: 'Menu', onSelect: openSheet },
36
36
  * ]} />
@@ -139,3 +139,5 @@ const AbPackageCardLegacy = ({ name, href, description, version, icon, media, id
139
139
  // 📦 exports
140
140
  export default AbPackageCard;
141
141
  export { AbPackageCard };
142
+ // 🖼️ 0.2.1 (God 02:44): the Home preview tiles (mock .pv-anim / .pv-code / .pv-comp)
143
+ export { AbPackagePreviewCurve, AbPackagePreviewCode, AbPackagePreviewComponents } from './previews';