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,203 @@
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: AbSettingsDrawer
28
+ * @file: ab-settings-drawer/index.tsx
29
+ * @type: Client component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * 1+|> const [open, setOpen] = useState(false)
34
+ * -|> <AbSettingsDrawer open={open} onClose={() => setOpen(false)} theme={mode} onThemeChange={setMode}
35
+ * -|> locales={[{ code: 'en', label: 'English' }, { code: 'fr', label: 'FranΓ§ais' }]} locale="en" onLocaleChange={go} />
36
+ */
37
+
38
+ /*
39
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40
+ * MOTTO: We'll always do more 😜!!!
41
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
42
+ */
43
+
44
+
45
+ 'use client';
46
+
47
+ // βš›οΈ React
48
+ import { useRef, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
49
+ // 🧡 classes
50
+ import clsx from 'clsx';
51
+ // πŸ—„οΈ the drawer (tiers, snap points, centring)
52
+ import AbDrawer, { type AbSheetSnap } from '../ab-drawer';
53
+ // πŸ”£ icons
54
+ import AbIcon from '../ab-icon';
55
+ // πŸ‘€ 0.2.1: the account row's avatar
56
+ import AbProfileAvatar, { type AbProfileUser } from '../ab-profile-avatar';
57
+ // 🎨 the drawers v2 kit
58
+ import kit from '../ab-drawer/kit.module.css';
59
+
60
+ /** πŸŒ— a theme choice */
61
+ export type AbSettingsTheme = 'light' | 'dark' | 'system';
62
+ /** 🌍 a language row */
63
+ export interface AbSettingsLocale { code: string; label: string } // 🏷️ `label` in its own language ("Français")
64
+
65
+ /** 🏷️ every visible / accessible string (English defaults) */
66
+ export interface AbSettingsDrawerLabels {
67
+ title?: string; // "Settings"
68
+ theme?: string; // "Theme"
69
+ language?: string; // "Language"
70
+ light?: string; dark?: string; system?: string; // πŸŒ—
71
+ close?: string; // "Close settings"
72
+ expand?: string; collapse?: string; // βž– the handle: "Expand settings" / "Collapse settings"
73
+ account?: string; // πŸ‘€ 0.2.1: the section label "Account"
74
+ signIn?: string; // πŸ”‘ 0.2.1: the signed-out row "Sign in"
75
+ help?: string; about?: string; // ❓ ℹ️ 0.2.1: "Help" / "About"
76
+ }
77
+
78
+ /** βš™οΈ props */
79
+ export interface AbSettingsDrawerProps {
80
+ open: boolean; // πŸšͺ
81
+ onClose: () => void; // βŽ‹
82
+ theme: AbSettingsTheme; // πŸŒ— the checked theme
83
+ onThemeChange: (theme: AbSettingsTheme) => void; // πŸ“£
84
+ locales: readonly AbSettingsLocale[]; // 🌍
85
+ locale: string; // 🎯 the checked locale code
86
+ onLocaleChange: (code: string) => void; // πŸ“£
87
+ labels?: AbSettingsDrawerLabels; // 🏷️
88
+ themes?: readonly AbSettingsTheme[]; // 🎚️ default light, dark, system
89
+ // πŸ‘€ 0.2.1 (God 02:44): the account section is back, on top. `account` = signed in (avatar, name, email);
90
+ // signed out, pass `onSignIn` for a "Sign in" row. Neither = no section.
91
+ account?: AbProfileUser | null;
92
+ onAccount?: () => void; // πŸ‘€ tap the signed-in row (e.g. open the profile page)
93
+ onSignIn?: () => void; // πŸ”‘
94
+ onHelp?: () => void; // ❓ 0.2.1: a "Help β€Ί" row after Language
95
+ onAbout?: () => void; // ℹ️ 0.2.1: an "About β€Ί" row after Help
96
+ children?: ReactNode; // βž• extra sections after Language (your own; Accessibility / About are not built in)
97
+ defaultSnap?: AbSheetSnap; // 🧲 default 'partial' (70%)
98
+ returnFocus?: string; // ↩️ see AbDrawer
99
+ id?: string; // πŸ†”
100
+ className?: string; // 🏷️
101
+ }
102
+
103
+ // βœ“ the 24px 2px-stroke check (the mock's path)
104
+ const Check = () => <svg className={kit.ck} viewBox="0 0 24 24" width="24" height="24" aria-hidden="true"><path d="M5 12.5l4.5 4.5L19 7.5" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" /></svg>;
105
+ // πŸŒ— the glyph per theme
106
+ const THEME_ICON: Record<AbSettingsTheme, string> = { light: 'light_mode', dark: 'dark_mode', system: 'brightness_auto' };
107
+
108
+ /** ⌨️ radiogroup keys: arrows move AND check (WAI-ARIA radio pattern), Home / End jump */
109
+ function radioKeys<T>(e: KeyboardEvent, items: readonly T[], current: T, pick: (v: T) => void, root: HTMLElement | null) {
110
+ const i = items.indexOf(current); let n = -1;
111
+ if (e.key === 'ArrowDown' || e.key === 'ArrowRight') n = (i + 1) % items.length;
112
+ else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') n = (i - 1 + items.length) % items.length;
113
+ else if (e.key === 'Home') n = 0; else if (e.key === 'End') n = items.length - 1;
114
+ if (n < 0) return;
115
+ e.preventDefault(); pick(items[n]); // βœ… check it
116
+ root?.querySelectorAll<HTMLElement>('[role="radio"]')[n]?.focus(); // 🎯 and move focus
117
+ }
118
+
119
+ /**
120
+ * βš™οΈ AbSettingsDrawer β€” John's Settings bottom drawer (drawers v2, spec Β§1): the default bottom sheet, holding
121
+ * ACCOUNT (0.2.1, optional), THEME (a Light / Dark / System segmented radiogroup, 48px) and LANGUAGE (48px radio rows, each label in its
122
+ * own `lang`, the checked one tinted with a check), then optional Help / About rows (0.2.1).
123
+ *
124
+ * - πŸ“± below 768px: full width, snaps at 70% and full height via the handle (AbDrawer `snapPoints`)
125
+ * - πŸ’» 768px and up: centred in the main pane, min(640px, main width), at most 70% tall
126
+ * - β™Ώ `role="dialog"` labelled by the title; focus goes to the checked language on open (so the globe's
127
+ * "Change language" lands right there) and back to the opener on close; Esc / scrim / βœ• close it
128
+ * - πŸ₯ž tier 'sheet': above the left and right drawers. Opening it from the left drawer? Close that one first.
129
+ */
130
+ const AbSettingsDrawer = ({ open, onClose, theme, onThemeChange, locales, locale, onLocaleChange, labels = {}, account, onAccount, onSignIn, onHelp, onAbout, themes = ['light', 'dark', 'system'], children, defaultSnap, returnFocus, id, className }: AbSettingsDrawerProps): ReactElement => {
131
+ const seg = useRef<HTMLDivElement>(null); // 🎚️
132
+ const langs = useRef<HTMLDivElement>(null); // 🌍
133
+ const L = { title: 'Settings', theme: 'Theme', language: 'Language', light: 'Light', dark: 'Dark', system: 'System', close: 'Close settings', expand: 'Expand settings', collapse: 'Collapse settings', account: 'Account', signIn: 'Sign in', help: 'Help', about: 'About', ...labels }; // 🏷️
134
+ const base = id ?? 'ab-settings'; // πŸ†”
135
+ const codes = locales.map((l) => l.code); // 🌍
136
+ return (
137
+ <AbDrawer
138
+ open={open} onClose={onClose} id={id} side="bottom" scope="app" tier="sheet"
139
+ snapPoints centerIn="main" defaultSnap={defaultSnap} handleLabels={{ expand: L.expand, collapse: L.collapse }}
140
+ title={L.title} closeLabel={L.close} closeIcon={<AbIcon name="close" size={24} />}
141
+ initialFocus='[data-ab-part="settings-language"] [aria-checked="true"]' returnFocus={returnFocus}
142
+ className={clsx('AbSettingsDrawer', kit.sheet, className)}
143
+ >
144
+ {/* πŸ‘€ 0.2.1: ACCOUNT (signed in: avatar Β· name Β· email; signed out: "Sign in") */}
145
+ {(account || onSignIn) && (
146
+ <section aria-labelledby={`${base}-account`} data-ab-part="settings-account">
147
+ <p className={kit.lbl} id={`${base}-account`}>{L.account}</p>
148
+ {account ? (
149
+ onAccount ? ( // πŸ‘† tappable: a button with a chevron
150
+ <button type="button" className={clsx(kit.row, kit.acct)} onClick={onAccount} data-ab-part="settings-account-row">
151
+ <AbProfileAvatar user={account} size={36} Icon={AbIcon} />
152
+ <span className={kit.acctText}><b>{account.name}</b>{account.email && <small>{account.email}</small>}</span>
153
+ <AbIcon name="chevron_right" size={24} className={kit.chev} />
154
+ </button>
155
+ ) : ( // πŸͺ§ info only: plain row, not a dead button
156
+ <div className={clsx(kit.row, kit.acct)} data-ab-part="settings-account-row">
157
+ <AbProfileAvatar user={account} size={36} Icon={AbIcon} />
158
+ <span className={kit.acctText}><b>{account.name}</b>{account.email && <small>{account.email}</small>}</span>
159
+ </div>
160
+ )
161
+ ) : (
162
+ <button type="button" className={clsx(kit.row, kit.acct)} onClick={onSignIn} data-ab-part="settings-sign-in">
163
+ <AbProfileAvatar size={36} Icon={AbIcon} /><span>{L.signIn}</span><AbIcon name="chevron_right" size={24} className={kit.chev} />
164
+ </button>
165
+ )}
166
+ </section>
167
+ )}
168
+ <p className={kit.lbl} id={`${base}-theme`}>{L.theme}</p>
169
+ <div ref={seg} className={kit.seg} role="radiogroup" aria-labelledby={`${base}-theme`} data-ab-part="settings-theme">
170
+ {themes.map((t) => (
171
+ <button key={t} type="button" role="radio" aria-checked={t === theme} tabIndex={t === theme ? 0 : -1} className={kit.segBtn} data-value={t}
172
+ onClick={() => onThemeChange(t)} onKeyDown={(e) => radioKeys(e, themes, theme, onThemeChange, seg.current)}>
173
+ <AbIcon name={THEME_ICON[t]} size={18} />{L[t]}
174
+ </button>
175
+ ))}
176
+ </div>
177
+ <p className={kit.lbl} id={`${base}-language`}>{L.language}</p>
178
+ <div ref={langs} role="radiogroup" aria-labelledby={`${base}-language`} data-ab-part="settings-language">
179
+ {locales.map((l) => {
180
+ const on = l.code === locale; // 🎯
181
+ return (
182
+ <button key={l.code} type="button" role="radio" aria-checked={on} tabIndex={on ? 0 : -1} lang={l.code} className={kit.row} data-value={l.code}
183
+ onClick={() => onLocaleChange(l.code)} onKeyDown={(e) => radioKeys(e, codes, locale, onLocaleChange, langs.current)}>
184
+ {l.label}{on && <Check />}
185
+ </button>
186
+ );
187
+ })}
188
+ </div>
189
+ {/* ❓ ℹ️ 0.2.1: Help and About rows (back from 0.1.x), after Language */}
190
+ {(onHelp || onAbout) && (
191
+ <div className={kit.more} data-ab-part="settings-more">
192
+ {onHelp && <button type="button" className={kit.row} onClick={onHelp} data-ab-part="settings-help"><AbIcon name="help" size={24} /><span>{L.help}</span><AbIcon name="chevron_right" size={24} className={kit.chev} /></button>}
193
+ {onAbout && <button type="button" className={kit.row} onClick={onAbout} data-ab-part="settings-about"><AbIcon name="info" size={24} /><span>{L.about}</span><AbIcon name="chevron_right" size={24} className={kit.chev} /></button>}
194
+ </div>
195
+ )}
196
+ {children}
197
+ </AbDrawer>
198
+ );
199
+ };
200
+
201
+ // πŸ“¦ exports
202
+ export default AbSettingsDrawer;
203
+ export { AbSettingsDrawer };
@@ -32,7 +32,7 @@
32
32
  * Example usage:
33
33
  * <AbSidebar
34
34
  * activeHref="/docs/components"
35
- * sections={[{ id: 'docs', label: 'Docs', items: [{ href: '/docs/components', icon: 'widgets', label: 'Components' }] }]}
35
+ * sections={[{ id: 'gs', label: 'Getting started', items: [{ href: '/introduction', icon: 'description', label: 'Introduction' }] }]}
36
36
  * />
37
37
  */
38
38
 
@@ -56,16 +56,21 @@ import AbIcon from '../ab-icon';
56
56
  import { AbSidebarView, isAbSidebarActive, type AbSidebarBaseProps } from './view';
57
57
  // 🎨 styles
58
58
  import styles from './styles.module.css';
59
+ // πŸ‘€ 0.2.1 (God 02:44): the bottom-left profile button (β‰₯ 1180px, CSS)
60
+ import AbSidebarProfileButton, { type AbSidebarProfileButtonProps } from './profile-button';
59
61
 
60
62
  // πŸ“¦ re-export the shared types
61
63
  export type { AbSidebarItem, AbSidebarSection, AbSidebarLink, AbSidebarLabels } from './view';
62
64
  export { isAbSidebarActive, toAbSidebarSections } from './view';
65
+ export { AbSidebarProfileButton, type AbSidebarProfileButtonProps } from './profile-button';
63
66
 
64
67
  /** βš™οΈ Client props: the shared ones + collapse control. */
65
68
  export interface AbSidebarProps extends AbSidebarBaseProps {
66
69
  defaultCollapsed?: boolean; // πŸšͺ uncontrolled start
67
70
  onCollapsedChange?: (collapsed: boolean) => void; // πŸ””
68
71
  collapsible?: boolean; // πŸ”˜ show the collapse button (default true when sections are given)
72
+ // πŸ‘€ 0.2.1 (God 02:44): opt-in; pass `user` + the AbSettingsDrawer props for a profile button at the bottom left
73
+ profile?: Omit<AbSidebarProfileButtonProps, 'collapsed'>;
69
74
  collapseButtonVariant?: 'plain' | 'outlined'; // βͺ 0.1.14 (P9): 'outlined' = 32Γ—32 bordered `<<` / `>>` (default 'plain' chevron)
70
75
  }
71
76
 
@@ -106,7 +111,10 @@ const AbSidebar = (props: AbSidebarProps): ReactElement => {
106
111
  </button>
107
112
  ) : undefined;
108
113
 
109
- return <AbSidebarView props={{ ...props, collapsed }} Icon={AbIcon} active={active} toggle={toggle} />;
114
+ // πŸ‘€ 0.2.1: the profile button joins any custom footer (label from `labels.profile`)
115
+ const profileButton = props.profile ? <AbSidebarProfileButton label={labels?.profile ?? 'Profile and settings'} {...props.profile} collapsed={collapsed} /> : null;
116
+ const footer = profileButton || props.footer != null ? <>{profileButton}{props.footer}</> : undefined; // 🦢
117
+ return <AbSidebarView props={{ ...props, collapsed, footer }} Icon={AbIcon} active={active} toggle={toggle} />;
110
118
  };
111
119
 
112
120
  // πŸ“¦ exports
@@ -0,0 +1,115 @@
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: AbSidebarProfileButton - Client (0.2.1, God 02:44)
28
+ * @file: ab-sidebar/profile-button.tsx
29
+ * @type: Client Component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * <AbSidebar sections={…} profile={{ user: { name: 'Abraham Ukachi' }, theme, onThemeChange, locales, locale, onLocaleChange }} />
34
+ * <AbSidebarProfileButton user={null} theme={theme} onThemeChange={setTheme} locales={LOCALES} locale={locale} onLocaleChange={setLocale} />
35
+ */
36
+
37
+ /*
38
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
39
+ * MOTTO: We'll always do more 😜!!!
40
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
41
+ */
42
+
43
+
44
+ 'use client';
45
+
46
+ // βš›οΈ React
47
+ import { useId, useState, type ReactElement } from 'react';
48
+ // 🧡 classes
49
+ import clsx from 'clsx';
50
+ // πŸ”£ client AbIcon ("person" from ab-nextjs-icons; register it like every other app glyph)
51
+ import AbIcon from '../ab-icon';
52
+ // 🎈 the collapsed-rail hover / focus label (same as the rail items)
53
+ import AbBalloon from '../ab-balloon';
54
+ // πŸ‘€ the circle: initials, photo or the profile glyph
55
+ import AbProfileAvatar, { type AbProfileUser } from '../ab-profile-avatar';
56
+ // βš™οΈ the drawer it opens
57
+ import AbSettingsDrawer, { type AbSettingsDrawerProps } from '../ab-settings-drawer';
58
+ // 🎨 styles (shared with the sidebar)
59
+ import styles from './styles.module.css';
60
+
61
+ /** βš™οΈ props: everything AbSettingsDrawer needs (minus the open state, which the button owns) + who is signed in */
62
+ export interface AbSidebarProfileButtonProps extends Omit<AbSettingsDrawerProps, 'open' | 'onClose' | 'className' | 'account'> {
63
+ user?: AbProfileUser | null; // πŸ‘€ signed in (initials / photo) or signed out (null: the profile glyph)
64
+ label?: string; // β™ΏπŸŒ accessible name + collapsed tooltip (default "Profile and settings")
65
+ collapsed?: boolean; // πŸšͺ the sidebar is an icon rail: avatar only + a balloon tooltip
66
+ size?: number; // πŸ“ the avatar circle in px (default 40: "fairly large", the sidebar rows are 32)
67
+ showAccount?: boolean; // πŸ‘€ pass `user` on to the drawer's Account section (default true)
68
+ className?: string; // 🏷️ on the button
69
+ drawerClassName?: string; // 🏷️ on the drawer
70
+ onOpenChange?: (open: boolean) => void; // πŸ”” opened / closed
71
+ }
72
+
73
+ /**
74
+ * πŸ‘€ AbSidebarProfileButton β€” the bottom-left sidebar control (God 02:44, replaces the 0.2.1-draft settings icon
75
+ * button): a 40px profile circle (signed out: the profile glyph; signed in: the initials on the container colour, or
76
+ * the photo masked to a circle) + the name when the sidebar is expanded. Tapping it opens AbSettingsDrawer.
77
+ *
78
+ * - πŸ–₯️ always rendered (server too): CSS hides it below 1180px, so there's no JS gating and no first-paint flash
79
+ * - 🎈 collapsed rail: avatar only, and an AbBalloon names it on hover / focus
80
+ * - β™Ώ a real <button>: aria-label, aria-haspopup="dialog", aria-expanded + aria-controls the drawer
81
+ * - ↩️ focus goes back to the button when the drawer closes (AbDrawer remembers the opener)
82
+ */
83
+ const AbSidebarProfileButton = ({ user = null, label = 'Profile and settings', collapsed = false, size = 40, showAccount = true, className, drawerClassName, onOpenChange, id, ...drawer }: AbSidebarProfileButtonProps): ReactElement => {
84
+ const [open, setOpen] = useState(false); // πŸšͺ
85
+ const auto = useId(); // πŸ†” SSR-stable
86
+ const drawerId = id ?? `ab-sidebar-profile-${auto.replace(/:/g, '')}`; // πŸ†” aria-controls target
87
+ const set = (next: boolean) => { setOpen(next); onOpenChange?.(next); }; // πŸ””
88
+ const button = (
89
+ <button
90
+ type="button" // 🧾
91
+ className={clsx('AbSidebarProfileButton', styles.abSidebarProfile, className)} // 🎨
92
+ data-ab-part="sidebar-profile" // 🧩
93
+ data-signed-in={user ? 'true' : 'false'} // πŸ‘€
94
+ data-collapsed={collapsed ? 'true' : undefined} // πŸšͺ
95
+ aria-label={label} // 🏷️
96
+ aria-haspopup="dialog" // β™Ώ
97
+ aria-expanded={open} // β™Ώ
98
+ aria-controls={drawerId} // β™Ώ
99
+ onClick={() => set(!open)} // πŸ–±οΈ
100
+ >
101
+ <AbProfileAvatar user={user} size={size} Icon={AbIcon} /> {/* πŸ‘€ */}
102
+ {!collapsed && user && <span className={styles.abSidebarProfileName} aria-hidden="true">{user.name}</span> /* 🏷️ expanded: the name (the label already says it) */}
103
+ </button>
104
+ );
105
+ return (
106
+ <>
107
+ {collapsed ? <AbBalloon title={label} placement="end" strategy="fixed">{button}</AbBalloon> : button /* 🎈 rail tooltip (fixed: the rail scrolls / clips) */}
108
+ <AbSettingsDrawer {...drawer} account={showAccount ? user : undefined} id={drawerId} className={drawerClassName} open={open} onClose={() => set(false)} /> {/* πŸ—„οΈ */}
109
+ </>
110
+ );
111
+ };
112
+
113
+ // πŸ“¦ exports
114
+ export default AbSidebarProfileButton;
115
+ export { AbSidebarProfileButton };
@@ -187,3 +187,46 @@
187
187
  .abSidebar[data-density='compact'][data-collapsed='true'] .abSidebarHeader { padding: 12px 0 6px; justify-content: center; } /* πŸšͺ rail */
188
188
  .abSidebar[data-density='compact'][data-collapsed='true'] .abSidebarSections { padding-inline: 8px; }
189
189
  .abSidebar[data-density='compact'][data-collapsed='true'] .abSidebarLink { width: 40px; height: 40px; } /* πŸ‘† */
190
+
191
+ /* 🏷️ 0.1.15 (God 00:08): the tablet logo row, mock 06 `.sb-logo` = 60px, 0 20px, centred, never shrinks.
192
+ * Height follows core's --ab-header-height (60px at tablet) so it lines up with the main bar. */
193
+ .abSidebarLogo { flex: none; display: flex; align-items: center; box-sizing: border-box; height: var(--ab-header-height, 60px); padding: 0 20px; }
194
+ .abSidebar[data-collapsed='true'] .abSidebarLogo { justify-content: center; padding: 0; } /* πŸšͺ rail: centred */
195
+
196
+ /* 🦢 0.2.1: bottom-left slot (the profile button), pinned by margin-top: auto (the sidebar is a column) */
197
+ .abSidebarFooter {
198
+ display: flex; /* πŸ“ */
199
+ align-items: center; /* ↕️ */
200
+ gap: 8px; /* ↔️ */
201
+ margin-top: auto; /* ⬇️ pinned to the bottom */
202
+ padding-top: 8px; /* πŸ“¦ */
203
+ position: sticky; /* πŸ“Œ stays in view when the list scrolls */
204
+ bottom: 0; /* ⬇️ */
205
+ background: inherit; /* 🎨 the pane colour behind it */
206
+ }
207
+ .abSidebar[data-collapsed='true'] .abSidebarFooter { justify-content: center; } /* πŸšͺ rail: centred */
208
+ .abSidebar { min-height: 100%; } /* πŸ“ fill the pane so the footer can reach the bottom */
209
+ .abSidebar[data-density='compact'] .abSidebarFooter { padding: 8px 10px 12px; box-sizing: border-box; width: 100%; } /* πŸ“¦ compact: line up with the rows (sections pad 10px) */
210
+ /* πŸ‘€ 0.2.1 (God 02:44): the profile button: avatar (+ the name when expanded), theme tokens only */
211
+ .abSidebarProfile {
212
+ display: inline-flex; /* πŸ“ */
213
+ align-items: center; /* ↕️ */
214
+ gap: 10px; /* ↔️ */
215
+ max-width: 100%; /* πŸ“ */
216
+ min-height: 44px; /* πŸ‘† touch-size */
217
+ padding: 2px 10px 2px 2px; /* πŸ“¦ a pill around the circle */
218
+ border: 0; /* 🚫 */
219
+ border-radius: 999px; /* πŸ’Š */
220
+ background: transparent; /* 🎨 */
221
+ color: var(--ab-color-text, inherit); /* πŸ–‹οΈ */
222
+ font: 600 13.5px/1.2 var(--ab-font-body, inherit); /* πŸ”€ */
223
+ cursor: pointer; /* πŸ‘† */
224
+ }
225
+ .abSidebarProfile[data-collapsed='true'], .abSidebarProfile[data-signed-in='false'] { padding: 2px; } /* β­• just the circle */
226
+ @media (hover: hover) { .abSidebarProfile:hover { background: var(--ab-color-hover, color-mix(in srgb, currentColor 8%, transparent)); } } /* πŸ–±οΈ */
227
+ .abSidebarProfile[aria-expanded='true'] { background: var(--ab-color-hover, color-mix(in srgb, currentColor 8%, transparent)); } /* βœ… open */
228
+ .abSidebarProfile:focus { outline: none; } /* 🎯 */
229
+ .abSidebarProfile:focus-visible { outline: 2px solid var(--ab-color-accent, currentColor); outline-offset: 2px; } /* β™Ώ */
230
+ .abSidebarProfileName { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } /* 🏷️ */
231
+ /* πŸ“± mobile + tablet reach Settings another way: hidden by CSS (rendered on the server, no flash) */
232
+ @media (max-width: 1179.98px) { .abSidebarProfile { display: none; } }
@@ -79,6 +79,7 @@ export interface AbSidebarLabels {
79
79
  nav?: string; // β™Ώ nav aria-label (default "Sidebar")
80
80
  collapse?: string; // ◀️ (default "Collapse sidebar")
81
81
  expand?: string; // ▢️ (default "Expand sidebar")
82
+ profile?: string; // πŸ‘€ 0.2.1: the profile button (default "Profile and settings")
82
83
  }
83
84
 
84
85
  /** πŸ”£ What the view needs from an icon component (client and server AbIcon both fit). */
@@ -98,6 +99,10 @@ export interface AbSidebarBaseProps {
98
99
  density?: 'comfortable' | 'compact'; // πŸ“ 'compact' = 32px rows, 13.5/500, 18px icons, 11px group labels
99
100
  activeShape?: 'pill' | 'rounded'; // πŸ”· 'rounded' = 8px-radius --tint row (default 'pill')
100
101
  badgeVariant?: 'chip' | 'text'; // 🏷️ 'text' = plain mono 10.5 --faint meta (e.g. a version), no chip
102
+ // 🏷️ 0.1.15 (God 00:08): a 60px logo row above `header` (mock 06 `.sb-logo`). With core β‰₯ 0.2.1 panes it only shows
103
+ // where the app header is hidden (tabletHeader="main" at 768–1179); elsewhere it always shows
104
+ logo?: ReactNode;
105
+ footer?: ReactNode; // 🦢 0.2.1: a bottom slot pinned to the bottom left (e.g. AbSidebarProfileButton)
101
106
  // πŸ•°οΈ legacy API (≀ 0.1.12)
102
107
  type?: 'customer' | 'admin';
103
108
  page?: string;
@@ -155,7 +160,7 @@ export function AbSidebarView({ props, Icon, active, toggle }: {
155
160
  return (
156
161
  <li key={item.id ?? item.href}>
157
162
  {/* 🎈 rail: a balloon names the icon on hover / focus */}
158
- {collapsed && depth === 0 ? <AbBalloon title={text ?? item.href} placement="end">{link}</AbBalloon> : link}
163
+ {collapsed && depth === 0 ? <AbBalloon title={text ?? item.href} placement="end" strategy="fixed">{link}</AbBalloon> : link}
159
164
  {!collapsed && item.items?.length ? (
160
165
  <ul className={styles.abSidebarList} data-ab-part="children">{item.items.map((c) => renderItem(c, depth + 1))}</ul>
161
166
  ) : null}
@@ -174,6 +179,7 @@ export function AbSidebarView({ props, Icon, active, toggle }: {
174
179
  data-badge={badgeVariant === 'text' ? 'text' : undefined} // 🏷️ P8
175
180
  aria-label={labels?.nav ?? 'Sidebar'} // β™Ώ
176
181
  >
182
+ {props.logo != null && <div className={styles.abSidebarLogo} data-ab-part="sidebar-logo">{props.logo}</div> /* 🏷️ 0.1.15 */}
177
183
  {/* 🏷️ header slot, or the legacy brand link */}
178
184
  <div className={styles.abSidebarHeader}>
179
185
  {header ?? (links?.length && !sections?.length ? <Link href={brandHref} className={styles.abSidebarBrand}>{brandLabel}</Link> : null)}
@@ -187,6 +193,8 @@ export function AbSidebarView({ props, Icon, active, toggle }: {
187
193
  </section>
188
194
  ))}
189
195
  </div>
196
+ {/* 🦢 0.2.1: bottom-left slot (margin-top: auto pins it) */}
197
+ {props.footer != null && <div className={styles.abSidebarFooter} data-ab-part="sidebar-footer">{props.footer}</div>}
190
198
  </nav>
191
199
  );
192
200
  }
package/ab-toc/index.tsx CHANGED
@@ -129,3 +129,6 @@ const AbToc = ({ items, activeId, label, title = label ?? 'On this page', onNavi
129
129
  // πŸ“¦ exports
130
130
  export default AbToc;
131
131
  export { AbToc };
132
+
133
+ // πŸ†• 0.2.1 (God 02:44): the aside "New" card
134
+ export { AbTocPromo, type AbTocPromoProps } from './promo';
@@ -0,0 +1,74 @@
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: AbTocPromo (0.2.1, God 02:44, mock .toc-card)
28
+ * @file: ab-toc/promo.tsx
29
+ * @type: React Component (no hooks: client + server)
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage (in AbToc `footer`, or anywhere in the aside):
33
+ * <AbTocPromo title="BottomNav & Sheet" href="/changelog">Now in <code>ab-nextjs-components</code></AbTocPromo>
34
+ */
35
+
36
+ /*
37
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
38
+ * MOTTO: We'll always do more 😜!!!
39
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40
+ */
41
+
42
+ // βš›οΈ React
43
+ import type { ReactElement, ReactNode } from 'react';
44
+ // 🧡 classes
45
+ import clsx from 'clsx';
46
+ // πŸ”— injectable link
47
+ import Link from '../ab-link';
48
+ // 🎨 styles
49
+ import styles from './styles.module.css';
50
+
51
+ /** βš™οΈ props */
52
+ export interface AbTocPromoProps {
53
+ title: ReactNode; // 🏷️ 13px bold, e.g. "BottomNav & Sheet"
54
+ children?: ReactNode; // πŸ“ the 11.5px muted subtitle (a `<code>` inside is 10.5px)
55
+ badge?: ReactNode; // πŸ†• the small chip (default "New"; `null` = none)
56
+ href?: string; // πŸ”— makes the title a link (the whole card clicks)
57
+ className?: string; // 🏷️
58
+ }
59
+
60
+ /**
61
+ * πŸ†• AbTocPromo β€” the aside's "New" card (mock `.toc-card`): a rounded (12px), evenly padded (12px) container on
62
+ * the card colour with a 1px border; a small "New" chip, a smaller title and a relatively smaller subtitle.
63
+ */
64
+ const AbTocPromo = ({ title, children, badge = 'New', href, className }: AbTocPromoProps): ReactElement => (
65
+ <aside className={clsx('AbTocPromo', styles.abTocPromo, className)} data-ab-part="toc-promo">
66
+ {badge != null && <span className={styles.abTocPromoChip}>{badge}</span> /* πŸ†• */}
67
+ <b className={styles.abTocPromoTitle}>{href ? <Link href={href} className={styles.abTocPromoLink}>{title}</Link> : title}</b> {/* 🏷️ */}
68
+ {children != null && <small className={styles.abTocPromoText}>{children}</small> /* πŸ“ */}
69
+ </aside>
70
+ );
71
+
72
+ // πŸ“¦ exports
73
+ export default AbTocPromo;
74
+ export { AbTocPromo };
@@ -64,3 +64,19 @@
64
64
  .abTocFooter a:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; border-radius: 4px; } /* β™Ώ */
65
65
  .abTocFooter a svg { flex: none; width: 15px; height: 15px; color: var(--ab-color-faint, inherit); } /* πŸ”£ GitHub Β· north_east */
66
66
  .abTocFooter > ul { list-style: none; margin: 0; padding: 0; }
67
+
68
+ /* πŸ†• 0.2.1 (God 02:44): AbTocPromo, the aside "New" card (mock .toc-card), theme tokens only */
69
+ .abTocPromo {
70
+ position: relative; /* πŸ“Œ the stretched link */
71
+ display: flex; flex-direction: column; align-items: flex-start; gap: 6px; /* πŸ“ */
72
+ margin-top: 16px; padding: 12px; box-sizing: border-box; /* πŸ“¦ evenly padded */
73
+ border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); border-radius: 12px; /* πŸ”² rounded */
74
+ background: var(--ab-color-card, #fff); color: var(--ab-color-text, #211a16); /* 🎨 */
75
+ }
76
+ .abTocPromoChip { display: inline-flex; align-items: center; height: 20px; padding: 0 7px; border-radius: 6px; font: 600 11px/1 var(--ab-font-code, ui-monospace, monospace); color: var(--ab-color-accent-text, #88603d); background: var(--ab-color-tint, #f4e7db); } /* πŸ†• */
77
+ .abTocPromoTitle { font-size: 13px; font-weight: 700; line-height: 1.3; } /* 🏷️ smaller title */
78
+ .abTocPromoText { font-size: 11.5px; line-height: 1.4; color: var(--ab-color-muted, #6b5b50); } /* πŸ“ relatively smaller */
79
+ .abTocPromoText code { font-size: 10.5px; font-family: var(--ab-font-code, ui-monospace, monospace); } /* ⌨️ */
80
+ .abTocPromoLink { color: inherit; text-decoration: none; } /* πŸ”— */
81
+ .abTocPromoLink::after { content: ''; position: absolute; inset: 0; border-radius: inherit; } /* πŸ–±οΈ whole card */
82
+ .abTocPromo:has(.abTocPromoLink:focus-visible) { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; } /* β™Ώ */