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
package/CHANGELOG.md CHANGED
@@ -1,3 +1,52 @@
1
+ ## 0.2.1 (Unreleased, proposed)
2
+
3
+ ### Sidebar profile (God 02:44)
4
+ - ✨ AbSidebar `profile` prop (opt-in): a 40px profile button at the bottom left opens AbSettingsDrawer. Signed out it shows the profile glyph; signed in the initials ("AU") on the container colour, or the photo masked to a circle, plus the name when expanded. Rendered on the server and hidden by CSS below 1180px (no flash); the collapsed rail names it with an AbBalloon tooltip. Label via `labels.profile` (default "Profile and settings")
5
+ - ✨ New `AbSidebarProfileButton` (standalone) and `AbProfileAvatar` + `getAbInitials` (client + server)
6
+ - ✨ AbSidebar `footer` slot (bottom left, sticky)
7
+ - ✨ AbBalloon `strategy="fixed"`: the tip is placed in the viewport, so the collapsed sidebar rail (a scroller) can't clip it; rail items + the profile button use it
8
+ - ✨ AbTocPromo: the aside "New" card (mock .toc-card: 12px radius + padding, card colour, 13px title, 11.5px subtitle)
9
+ - ✨ Home preview tiles for AbPackageCard `preview`: `AbPackagePreviewCurve` (ease-out), `AbPackagePreviewCode` (`*kw*` / `~dim` lines), `AbPackagePreviewComponents` (button · switch · pill chip); preview children no longer stretch
10
+ - ✨ `useAbEdgeSwipe({ maxWidth })` + `AB_ASIDE_DRAWER_MAX_WIDTH` (1179): the right drawer swipes on mobile and tablet only (God 02:47)
11
+ - 🐛 Drawers: a swipe-opened drawer returns focus to the header / brand logo by default (`AB_DRAWER_RETURN_FOCUS`; AbAppBar's brand gets `data-ab-part="app-bar-brand"`) (Joseph)
12
+ - 🐛 Drawer rows: hover tints only on hover-capable pointers, so the nav drawer opens with no highlighted row (Joseph)
13
+ - ✨ AbSettingsDrawer: the Account section is back on top (`account`, `onAccount`, `onSignIn`), plus `onHelp` / `onAbout` rows after Language (labels `account`, `signIn`, `help`, `about`)
14
+
15
+ ## 0.2.0 (Unreleased, proposed)
16
+
17
+ Includes everything planned for 0.1.15, which is not released separately.
18
+
19
+ ### ⚠️ Heads-up (default changes, not breaking)
20
+
21
+ * ⚠️ **AbVersionSwitcher `label`** now defaults to `''` (it was `'Docs'`), so the control shows just "v0.2.x ▾". Its accessible name is then `Version v0.2.x`. Pass `label="Docs"` for the old look.
22
+ * ⚠️ **AbAppBar compact bars** (`density="compact"`) now show the search **pill** below 768px by default (it used to be a 40px icon circle). Pass `compactSearch="icon"` for the old look.
23
+
24
+ ### Drawers v2
25
+ - ✨ AbDrawer: `tier`, `swipe`, `snapPoints`/`defaultSnap`/`fullOnly`/`onSnapChange`, `handleLabels`, `centerIn="main"`, `initialFocus` selector, `returnFocus`, `closeIcon`, `headerStart` (all additive)
26
+ - ✨ Gesture kit: `AB_SWIPE`, `resolveAbSheetRelease`, `resolveAbSideRelease`, `isInAbEdgeZone`, `createAbVelocityTracker`, `useAbEdgeSwipe`
27
+ - ✨ New: AbSettingsDrawer, AbNavDrawer, AbTocDrawer, AbSearchDrawer (combobox/listbox, recents, grouped results), AbMobileHeader
28
+ - 🔥 Docs removed from examples; AbVersionSwitcher `label` defaults to ''
29
+ - 🐛 Initial focus no longer scrolls the layer; returnFocus takes the first visible match
30
+ - ♿ AbVersionSwitcher: with no `label`, the accessible name is `Version <version>`
31
+ - 🧯 AbSearchDrawer: a rejected or throwing `search` clears to "no results"; no stale results, no unhandled rejection
32
+ - 🆔 AbSearchDrawer: group heading ids are sanitised (`[A-Za-z0-9_-]`) and indexed, so they stay valid and unique
33
+ - 📌 AbMobileHeader needs ab-nextjs-core ≥ 0.2.1 with `mobileHeader="main"`
34
+ - 🤖 Edge swipes work on Android Chrome: touches are read from touch events, and `touchmove` is non-passive only during an edge press, with `preventDefault` only once the move is sideways. Vertical scrolling from the edge zone and sideways code blocks are unaffected; checked in WebKit and Chromium touch emulation.
35
+
36
+ ### From 0.1.15
37
+
38
+ * 🔎 **AbAppBar `compactSearch`** (`'pill'` | `'icon'`): below 768px, a `density="compact"` bar now shows its `variant="field"` search as the mock's 34px "Search ⌘K" pill, not a 40px icon circle. It is the same element, styled by CSS, so there's still one hotkey listener. The default is `'pill'` for compact bars; comfortable bars keep the icon, as before.
39
+ * ⚠️ **Heads-up:** `density="compact"` bars now show the search pill below 768px by default (they used to show a 40px icon circle). Pass `compactSearch="icon"` to keep the old look.
40
+ * 🏷️ **AbSearchTrigger `compactLabel`:** an optional short label (e.g. "Search") that the compact bar shows on mobile instead of `label` ("Search docs…"). Only one is ever displayed. The key cap's space is now its own span, so the pill shows "⌘K".
41
+ * 🏷️ **AbSidebar `logo`:** a 60px (`--ab-header-height`) logo row above `header`, like mock 06's `.sb-logo`. With core ≥ 0.2.1 panes it only shows where the app header is hidden (`tabletHeader="main"` at 768–1179px).
42
+ * 🧩 **AbLocaleSwitcher `presentation="inline"`:** no trigger and no popover; it renders a labelled group of 48px rows (`--tint` + `--accent-text` when active, a check mark, `lang` / `hreflang`) in place. Put it inside the mobile app drawer. Link rows mark the current locale with `aria-current`, button rows with `aria-pressed`. Rows are exactly 48px (44px minimum), 8px apart, with an 18px bronze 2px-stroke check (`--ab-color-btn` light, `--ab-color-accent` dark). Use `divider` when it goes last after nav / theme items, and `showLabel={false}` when it's the drawer's only content (title the drawer "Language"). See the snippet in `ab-locale-switcher/index.tsx`. The inline list is its own component (`AbLocaleSwitcherInline`, also exported), so changing `presentation` at runtime remounts cleanly.
43
+ * 🏷️ **AbBottomDrawer title:** Mulish (`--ab-font-title`) 16/**800** (was 700). The bottom padding stays 16px + the safe area.
44
+ * 🔗 **AbAppBar `searchCompact`:** a node shown instead of `search` below 768px (both rendered, CSS picks). Pass `<AbSearchTrigger size="sm" href="/docs" label="Search" />` for the mock's mobile pill: a plain link to /docs, 114px wide (`--ab-app-bar-compact-search-width`) in a compact bar, with no ⌘K cap and no hotkey (no `onOpen` means no shortcut; `hotkey={false}` also turns both off).
45
+ * ♿ **Inline AbLocaleSwitcher `ariaLabel`:** the group's accessible name. It defaults to `label`, whether the label is visible or hidden.
46
+ * 📱 **No globe on the mobile bar:** pass the bar's actions without the locale switcher as `compactActions` (from 0.1.13), and render the inline switcher in the app drawer.
47
+ * 📝 **AbAppBar `searchCompact` docs:** a hotkey trigger passed to both `search` and `searchCompact` registers ⌘K twice; give only one `onOpen` (or `hotkey={false}` on the other).
48
+ * ✂️ **AbAppBar compact pill:** a longer (translated) label ends in an ellipsis inside the 114px pill.
49
+
1
50
  ## [0.1.14](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.1.13...v0.1.14) (2026-10-20)
2
51
 
3
52
  * ⬆️ **Peer + dev range:** `ab-nextjs-theme` **^0.3.5** (was ^0.3.4), for the Home tokens. It has a D33 release-age pin that expires 2026-10-21T20:40:07Z. Components doesn't depend on `ab-nextjs-core`, so no core range changed.
package/README.md CHANGED
@@ -126,6 +126,11 @@ A drawer belongs to a **region**: the whole app, the main pane or the aside pane
126
126
  * **Presets.** `<AbDrawerList>` is one selectable list: `items={[{ value, label, description?, icon?, href?, lang?, disabled? }]}`, `value`, `onSelect`, `closeOnSelect`, with the current item marked `aria-current`. `<AbConfirmDrawer>` takes `message`, `confirmLabel`, `cancelLabel`, `onConfirm`, `onCancel`, `tone="danger"` and `busy`. Escape, the scrim and ✕ count as cancel.
127
127
  * **G56:** `<AbLocaleSwitcher presentation="drawer" | "auto">` and `<AbAppBar presentation="drawer" | "auto">` (the More menu) open as an app-scope bottom `AbDrawerList`. `auto` opens a drawer below 768px and a menu above. The default stays `menu`.
128
128
 
129
+ ### Drawers v2 (0.2.0)
130
+
131
+ * **`<AbMobileHeader>`** (logo · globe · theme toggle) needs **ab-nextjs-core ≥ 0.2.1** with `<AbAppLayout variant="panes" mobileHeader="main">`. Pass it as `mainHeader`; core hides the app header below 768px and makes the main header the 56px mobile bar.
132
+ * **Edge swipes (`useAbEdgeSwipe`, `AbNavDrawer`/`AbTocDrawer` `swipe`):** a touch starting in the 24px edge zone is read from touch events. A non-passive `touchmove` listener exists only while that touch is down, and it calls `preventDefault` only once the move is sideways, so Android Chrome can't cancel it for a pan. Vertical scrolling from the edge, sideways code blocks and `[data-ab-no-edge-swipe]` keep working. Checked on WebKit and Chromium touch emulation.
133
+
129
134
  ## Getting Started
130
135
 
131
136
  ### Installation
@@ -33,8 +33,8 @@
33
33
  * <AbAppBar
34
34
  * brand={<AbBrand />}
35
35
  * search={<AbSearchTrigger onOpen={openSearch} />}
36
- * nav={[{ href: '/docs', label: 'Docs' }, { href: '/components', label: 'Components' }]}
37
- * activeHref="/docs"
36
+ * nav={[{ href: '/packages', label: 'Packages' }, { href: '/guides', label: 'Guides' }]}
37
+ * activeHref="/packages"
38
38
  * actions={<AbThemeToggle />}
39
39
  * />
40
40
  */
@@ -94,6 +94,16 @@ export interface AbAppBarProps {
94
94
  divider?: boolean;
95
95
  /** ⋮ 0.1.14 (P19): `false` = no "More" button/menu; below 1180px the nav is simply hidden (default `true`) */
96
96
  moreMenu?: boolean;
97
+ /** 🔎 0.1.15 (God 00:08): below 768px the search shows as a `'pill'` ("Search ⌘K", the Home mock) or an `'icon'`
98
+ * (40px circle, label for screen readers only). Default `'pill'` with `density="compact"`, else `'icon'` (unchanged). */
99
+ compactSearch?: 'pill' | 'icon';
100
+ /** 🔗 0.1.15 (God 00:37): shown INSTEAD of `search` below 768px (both rendered, CSS picks: no hydration flip), e.g.
101
+ * `<AbSearchTrigger size="sm" label="Search" onOpen={openSearchDrawer} hotkey={false} />`: a button that opens
102
+ * AbSearchDrawer, with no ⌘K cap and no hotkey (God 01:27: there is no /docs page; `href` still makes a plain link).
103
+ * In a compact bar it is the mock's 114px pill (`--ab-app-bar-compact-search-width`).
104
+ * ⚠️ Both slots are rendered: a hotkey trigger (with `onOpen`) passed to BOTH `search` and `searchCompact` registers ⌘K
105
+ * twice (one press opens twice). Give only one of them `onOpen`, or pass `hotkey={false}` to the other. */
106
+ searchCompact?: ReactNode;
97
107
  }
98
108
 
99
109
  /** 🎯 exact match or parent prefix ("/" only matches itself) */
@@ -103,7 +113,7 @@ const isActive = (href: string, active?: string) => !!active && (href === active
103
113
  * 🧱 AbAppBar (G43): brand, search, nav, actions, sticky with a hairline. Below 1180px the nav moves into a
104
114
  * "More" overflow menu built on AbMenu (G26). JS off: the More button is hidden and the nav scrolls inline.
105
115
  */
106
- const AbAppBar = ({ brand, search, nav = [], activeHref, locales, actions, compactActions, leading, sticky = true, labels, className, presentation = 'menu', density = 'comfortable', divider = false, moreMenu = true }: AbAppBarProps): ReactElement => {
116
+ const AbAppBar = ({ brand, search, nav = [], activeHref, locales, actions, compactActions, leading, sticky = true, labels, className, presentation = 'menu', density = 'comfortable', divider = false, moreMenu = true, compactSearch, searchCompact }: AbAppBarProps): ReactElement => {
107
117
  // 🌍 the active link comes from the AbLinkProvider locales, same rule as AbSidebar / AbNavbar
108
118
  const appLocales = useAbLocales();
109
119
  const pathname = stripAbLocalePrefix(usePathname() ?? '', locales ?? appLocales); // 🧭 `/fr/docs` → `/docs`
@@ -136,10 +146,11 @@ const AbAppBar = ({ brand, search, nav = [], activeHref, locales, actions, compa
136
146
  }, [open, mode]);
137
147
 
138
148
  return (
139
- <header className={clsx('AbAppBar', styles.abAppBar, className)} data-ab-part="app-bar" data-sticky={sticky ? 'true' : 'false'} data-has-compact-actions={compactActions != null ? 'true' : undefined} data-density={density === 'compact' ? 'compact' : undefined} data-more={moreMenu ? undefined : 'false'}>
149
+ <header className={clsx('AbAppBar', styles.abAppBar, className)} data-ab-part="app-bar" data-sticky={sticky ? 'true' : 'false'} data-has-compact-actions={compactActions != null ? 'true' : undefined} data-density={density === 'compact' ? 'compact' : undefined} data-more={moreMenu ? undefined : 'false'} data-compact-search={(compactSearch ?? (density === 'compact' ? 'pill' : 'icon')) === 'pill' ? 'pill' : undefined}>
140
150
  {leading}
141
- {brand && <div className={styles.abAppBarBrand}>{brand}</div>}
142
- {search && <div className={styles.abAppBarSearch}>{search}</div>}
151
+ {brand && <div className={styles.abAppBarBrand} data-ab-part="app-bar-brand">{brand}</div> /* 🏷️ 0.2.1: the drawers' default return-focus target */}
152
+ {search && <div className={styles.abAppBarSearch} data-when={searchCompact != null ? 'wide' : undefined}>{search}</div>}
153
+ {searchCompact != null && <div className={styles.abAppBarSearch} data-when="compact">{searchCompact}</div> /* 📱 0.1.15 */}
143
154
  {nav.length > 0 && (
144
155
  <nav className={styles.abAppBarNav} aria-label={labels?.nav ?? 'Main'}>
145
156
  <ul>
@@ -111,8 +111,8 @@
111
111
  .abAppBar { gap: 8px; padding-inline: max(12px, env(safe-area-inset-left, 0px)) max(8px, env(safe-area-inset-right, 0px)); } /* 📦 */
112
112
  .abAppBarBrand { flex: 0 1 auto; min-width: 0; overflow: hidden; } /* 🏷️ may shrink */
113
113
  .abAppBarSearch { flex: none; margin-inline-start: auto; } /* 🔎 icon only, pushed right */
114
- .abAppBarSearch > :global(.AbSearchTrigger):not([data-size='sm']) { width: 40px; min-width: 40px; padding: 0; justify-content: center; flex: none; } /* 🔘 */
115
- .abAppBarSearch > :global(.AbSearchTrigger):not([data-size='sm']) > :not(:global(.AbIcon)) { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; } /* 🕶️ label + kbd */
114
+ .abAppBar:not([data-compact-search='pill']) .abAppBarSearch > :global(.AbSearchTrigger):not([data-size='sm']) { width: 40px; min-width: 40px; padding: 0; justify-content: center; flex: none; } /* 🔘 */
115
+ .abAppBar:not([data-compact-search='pill']) .abAppBarSearch > :global(.AbSearchTrigger):not([data-size='sm']) > :not(:global(.AbIcon)) { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; } /* 🕶️ label + kbd */
116
116
  .abAppBarActions { margin-inline-start: 0; gap: 0; } /* 🔘 */
117
117
  .abAppBar[data-has-compact-actions='true'] .abAppBarActionsWide { display: none; } /* 🙈 */
118
118
  .abAppBar[data-has-compact-actions='true'] .abAppBarActionsCompact { display: flex; } /* 👀 */
@@ -156,3 +156,28 @@
156
156
  .abAppBar[data-density='compact'] .abAppBarSearch { margin-inline: auto 4px; } /* 🔎 pushed right, 4px before the icon */
157
157
  .abAppBar[data-density='compact'] .abAppBarActions { gap: 0; }
158
158
  }
159
+
160
+ /* ===== 🔎 0.1.15 (God 00:08, Joseph fidelity-2 #1): compactSearch="pill" below 768px =====
161
+ * The desktop field becomes the mobile mock's `.mpill`: 34px, pill radius, 13px "Search" + a tight "⌘K" cap.
162
+ * Same element, CSS only (no hydration flip, one hotkey listener). */
163
+ @media (max-width: 767px) {
164
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch > :global(.AbSearchTrigger)[data-variant='field'] {
165
+ flex: none; width: auto; max-width: none; height: 34px; gap: 6px; padding: 0 6px 0 10px; /* 📏 = size="sm" */
166
+ border-radius: var(--ab-radius-pill, 999px); font-size: 13px; /* 💊 🔤 */
167
+ }
168
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch > :global(.AbSearchTrigger)[data-variant='field'] > :global(.AbIcon) { width: 17px; height: 17px; font-size: 17px; } /* 🔣 17px */
169
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch > :global(.AbSearchTrigger)[data-variant='field'] > :global(.AbIcon) svg { width: 17px; height: 17px; }
170
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch :global(.AbSearchTrigger)[data-variant='field']:has([data-ab-part='search-label-compact']) [data-ab-part='search-label'] { display: none; } /* 🏷️ long label out… */
171
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch :global(.AbSearchTrigger)[data-variant='field'] [data-ab-part='search-label-compact'] { display: inline; } /* …"Search" in */
172
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch :global(.AbSearchTrigger)[data-variant='field'] [data-ab-part='key-gap'] { display: none; } /* ⌨️ "⌘K" */
173
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch :global(.AbSearchTrigger)[data-variant='field'] :global(.AbKbd) { min-width: 18px; height: 18px; font-size: 10px; } /* 📱 = sm cap */
174
+ }
175
+
176
+ /* ===== 🔗 0.1.15 (God 00:37): `searchCompact` replaces `search` below 768px (mock .mpill = 114px, here a link) ===== */
177
+ .abAppBarSearch[data-when='compact'] { display: none; } /* 🙈 ≥ 768px */
178
+ @media (max-width: 767px) {
179
+ .abAppBarSearch[data-when='wide'] { display: none; } /* 🙈 */
180
+ .abAppBarSearch[data-when='compact'] { display: block; } /* 👀 */
181
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch[data-when='compact'] > :global(.AbSearchTrigger) { width: var(--ab-app-bar-compact-search-width, 114px); box-sizing: border-box; } /* 📏 mock 114 */
182
+ .abAppBar[data-compact-search='pill'] .abAppBarSearch[data-when='compact'] > :global(.AbSearchTrigger) [data-ab-part^='search-label'] { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } /* ✂️ James P2: longer translations end in … inside the 114px pill */
183
+ }
@@ -44,7 +44,9 @@
44
44
  'use client';
45
45
 
46
46
  // ⚛️ React
47
- import { cloneElement, isValidElement, useCallback, useEffect, useId, useRef, useState, type FocusEvent, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
47
+ import { cloneElement, isValidElement, useCallback, useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore, type CSSProperties, type FocusEvent, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
48
+ // 🌀 0.2.1: the fixed tip goes to <body> (out of the rail's stacking context)
49
+ import { createPortal } from 'react-dom';
48
50
  // 🧵 classes
49
51
  import clsx from 'clsx';
50
52
  // 🎬 the tooltip pops in with the package keyframes (reduced-motion safe in ab-nextjs-animations)
@@ -52,6 +54,9 @@ import 'ab-nextjs-animations/pop-in/styles.css';
52
54
  // 🎨 styles
53
55
  import styles from './styles.module.css';
54
56
 
57
+ /** 🌀 a store that never changes: true on the client, false on the server */
58
+ const noSub = () => () => {};
59
+
55
60
  /** ⏱️ hover delay before the balloon shows (focus shows it at once). */
56
61
  export const AB_BALLOON_HOVER_DELAY = 300;
57
62
 
@@ -67,6 +72,9 @@ export interface AbBalloonProps {
67
72
  hidden?: boolean; // 🙈 render the child alone
68
73
  disabled?: boolean; // 🚫 no balloon
69
74
  children: ReactNode; // 🎯 the trigger (ideally ONE focusable element)
75
+ /** 📌 0.2.1: `'fixed'` = the tip is placed in the viewport from the trigger's box, so a scrolling / clipped parent
76
+ * (e.g. the collapsed sidebar rail) can't cut it off. Default `'absolute'` (relative to the wrapper). */
77
+ strategy?: 'absolute' | 'fixed';
70
78
  }
71
79
 
72
80
  /**
@@ -77,7 +85,7 @@ export interface AbBalloonProps {
77
85
  * - 🎬 `popIn` from ab-nextjs-animations (no motion under prefers-reduced-motion)
78
86
  * - 🚫 JS off: the balloon shows on `:focus-within` / `:hover` with CSS alone
79
87
  */
80
- const AbBalloon = ({ title, placement = 'top', delay = AB_BALLOON_HOVER_DELAY, className, hidden = false, disabled = false, children }: AbBalloonProps): ReactElement => {
88
+ const AbBalloon = ({ title, placement = 'top', delay = AB_BALLOON_HOVER_DELAY, className, hidden = false, disabled = false, children, strategy = 'absolute' }: AbBalloonProps): ReactElement => {
81
89
  // 🆔 tooltip id for aria-describedby
82
90
  const id = useId();
83
91
  // 👁️ open state
@@ -101,6 +109,21 @@ const AbBalloon = ({ title, placement = 'top', delay = AB_BALLOON_HOVER_DELAY, c
101
109
  }, []);
102
110
  // 🧹 unmount
103
111
  useEffect(() => clear, [clear]);
112
+ // 📌 0.2.1: fixed strategy: measure the trigger when it opens (6px gap, same as the CSS placements)
113
+ const root = useRef<HTMLSpanElement>(null);
114
+ const [pos, setPos] = useState<CSSProperties | undefined>(undefined);
115
+ const mounted = useSyncExternalStore(noSub, () => true, () => false); // 🌀 portals need the DOM (false on the server)
116
+ useLayoutEffect(() => {
117
+ if (strategy !== 'fixed' || !open || !root.current) return; // 🚫 absolute / closed
118
+ const r = root.current.getBoundingClientRect(); // 📐 the trigger box
119
+ const at: Record<NonNullable<AbBalloonProps['placement']>, CSSProperties> = {
120
+ top: { left: r.left + r.width / 2, top: r.top - 6 }, // ⬆️
121
+ bottom: { left: r.left + r.width / 2, top: r.bottom + 6 }, // ⬇️
122
+ start: { left: r.left - 6, top: r.top + r.height / 2 }, // ⬅️
123
+ end: { left: r.right + 6, top: r.top + r.height / 2 }, // ➡️
124
+ };
125
+ setPos(at[placement]); // 📍
126
+ }, [strategy, open, placement]);
104
127
 
105
128
  // 🙈 nothing to show
106
129
  if (hidden) return <>{children}</>;
@@ -145,6 +168,8 @@ const AbBalloon = ({ title, placement = 'top', delay = AB_BALLOON_HOVER_DELAY, c
145
168
  data-open={open ? 'true' : 'false'} // 👁️
146
169
  data-placement={placement} // 🧭
147
170
  data-ab-part="balloon" // 🧩
171
+ data-strategy={strategy === 'fixed' ? 'fixed' : undefined} // 📌 0.2.1
172
+ ref={root} // 📐
148
173
  onPointerEnter={onPointerEnter}
149
174
  onPointerLeave={onPointerLeave}
150
175
  onFocus={onFocus}
@@ -152,11 +177,18 @@ const AbBalloon = ({ title, placement = 'top', delay = AB_BALLOON_HOVER_DELAY, c
152
177
  onKeyDown={onKeyDown}
153
178
  >
154
179
  {trigger}
155
- {active && (
180
+ {active && strategy !== 'fixed' && (
156
181
  <span id={id} role="tooltip" className={clsx(styles.abBalloonTip, open && !still && 'popIn')} data-ab-part="balloon-tip">
157
182
  {title}
158
183
  </span>
159
184
  )}
185
+ {/* 📌 0.2.1 fixed: portalled to <body> so neither a scroller's clip nor a pane's stacking context can hide it */}
186
+ {active && strategy === 'fixed' && mounted && createPortal(
187
+ <span id={id} role="tooltip" className={clsx(styles.abBalloonTip, styles.abBalloonTipFixed, open && !still && 'popIn')} data-ab-part="balloon-tip" data-open={open ? 'true' : 'false'} data-placement={placement} style={pos}>
188
+ {title}
189
+ </span>,
190
+ document.body,
191
+ )}
160
192
  </span>
161
193
  );
162
194
  };
@@ -87,3 +87,11 @@
87
87
  .abBalloon[data-placement='end'] .abBalloonTip { inset-inline-start: calc(100% + 6px); top: 50%; translate: 0 -50%; }
88
88
 
89
89
  /* ♿ reduced motion: the component skips the popIn class (pop-in has no reduced-motion rule of its own) */
90
+
91
+ /* 📌 0.2.1: strategy="fixed": portalled to <body>, viewport-placed from the trigger's box (inline top / left) */
92
+ .abBalloonTipFixed { position: fixed; inset: auto; z-index: 1000; } /* 🧹 the absolute insets; above the panes */
93
+ .abBalloonTipFixed[data-open='true'] { display: block; } /* 👁️ open (it's no longer inside the wrapper) */
94
+ .abBalloonTipFixed[data-placement='top'] { translate: -50% -100%; } /* ⬆️ */
95
+ .abBalloonTipFixed[data-placement='bottom'] { translate: -50% 0; } /* ⬇️ */
96
+ .abBalloonTipFixed[data-placement='start'] { translate: -100% -50%; } /* ⬅️ */
97
+ .abBalloonTipFixed[data-placement='end'] { translate: 0 -50%; } /* ➡️ */
@@ -55,7 +55,7 @@
55
55
  width: 36px; height: 4px; margin: 8px auto 0; border-radius: 2px; /* 📏 */
56
56
  background: var(--ab-color-handle, rgb(25 18 12 / 0.18)); /* 🎨 dark: rgba(255,248,245,.18) via theme */
57
57
  }
58
- .abBottomDrawer h2 { font-family: var(--ab-font-title, inherit); font-size: 16px; font-weight: 700; letter-spacing: -0.01em; } /* 🏷️ */
58
+ .abBottomDrawer h2 { font-family: var(--ab-font-title, 'Mulish', inherit); font-size: 16px; font-weight: 800; letter-spacing: -0.01em; } /* 🏷️ John: Mulish 16/800 */
59
59
  /* ✕ close: 44px hit area, no border, 8px-radius hover tint (the Home icon buttons); ring on keyboard focus only */
60
60
  .abBottomDrawer [data-ab-part='drawer-close'] { inline-size: 44px; block-size: 44px; border: 0; border-radius: 8px; background: transparent; color: var(--ab-color-muted, #6b5b50); }
61
61
  .abBottomDrawer [data-ab-part='drawer-close']:hover { background: var(--ab-color-hover, rgb(166 124 82 / 0.08)); }
@@ -30,7 +30,7 @@
30
30
  * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
31
  *
32
32
  * Example usage:
33
- * 1+|> <AbBreadcrumbs items={[{ label: "Docs", href: "/docs" }, { label: "Home" }]} />
33
+ * 1+|> <AbBreadcrumbs items={[{ label: "Getting started", href: "/introduction" }, { label: "Installation" }]} />
34
34
  */
35
35
 
36
36
  /*
@@ -0,0 +1,134 @@
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 gestures
28
+ * @file: ab-drawer/gestures.ts
29
+ * @type: TypeScript — pure swipe / snap resolvers
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
33
+ /*
34
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35
+ * MOTTO: We'll always do more 😜!!!
36
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37
+ */
38
+
39
+ // 🤏 drawers v2 (John, God 01:22): the thresholds and decisions behind every drawer swipe, as pure functions,
40
+ // so the rules are unit-tested without a DOM and the components only feed them numbers.
41
+
42
+ /** 🎚️ the spec numbers (drawer-spec.md "Gestures" + "Edge zones") */
43
+ export const AB_SWIPE = {
44
+ ratio: 0.3, // 📏 30% of the travel / sheet / drawer width
45
+ velocity: 0.5, // ⚡ px per ms: at or above this a release counts as a fast swipe
46
+ edge: 24, // 🧱 edge zone width (px) for the side-drawer swipes
47
+ standaloneInset: 16, // 📱 iOS standalone: the zone starts 16px in (the system owns the very edge)
48
+ slop: 8, // 🫳 px of movement before a press becomes a drag (taps stay taps)
49
+ secondSwipe: 24, // ✌️ px: after a gentle return to S1, a swipe down this long closes (the "second swipe")
50
+ } as const;
51
+
52
+ /** 🧲 bottom-sheet snap states: S1 (`partial`, 70%), S2 (`full`) or gone */
53
+ export type AbSheetSnap = 'partial' | 'full';
54
+ /** 🏁 what a release resolves to */
55
+ export type AbSheetRelease = AbSheetSnap | 'closed';
56
+
57
+ /** 📥 one release of a bottom-sheet drag */
58
+ export interface AbSheetReleaseInput {
59
+ from: AbSheetSnap; // 🧲 where the drag started
60
+ dy: number; // ↕️ total movement, + = down
61
+ velocity: number; // ⚡ px/ms at release, + = down
62
+ partialHeight: number; // 📏 S1 height (70% of the app height)
63
+ fullHeight: number; // 📏 S2 height (app height minus the safe-area top)
64
+ returned?: boolean; // ✌️ the sheet came back to S1 from S2 with a gentle drag (so the next swipe down closes)
65
+ }
66
+
67
+ /**
68
+ * 🧲 resolveAbSheetRelease — where a released bottom sheet goes (spec §1 "Gestures"):
69
+ * - ⬆️ up past 30% of S1→S2, or faster than 0.5px/ms → `full`
70
+ * - ⬇️ at S2: fast (≥ 0.5px/ms) or past 30% of the sheet → `closed`; a gentle drag → back to `partial`
71
+ * - ⬇️ at S1: fast or past 30% of S1 → `closed`; after a gentle return from S2 any real swipe down (≥ 24px) → `closed`
72
+ * - otherwise it springs back to where it was
73
+ */
74
+ export function resolveAbSheetRelease({ from, dy, velocity, partialHeight, fullHeight, returned = false }: AbSheetReleaseInput): AbSheetRelease {
75
+ const fast = Math.abs(velocity) >= AB_SWIPE.velocity; // ⚡
76
+ if (dy < 0) { // ⬆️ up
77
+ if (from === 'full') return 'full'; // 🧱 already at the top
78
+ const travel = Math.max(1, fullHeight - partialHeight); // 📏 S1 → S2 distance
79
+ return -dy > AB_SWIPE.ratio * travel || (fast && velocity < 0) ? 'full' : 'partial'; // 🧲
80
+ }
81
+ if (from === 'full') { // ⬇️ from S2
82
+ if ((fast && velocity > 0) || dy > AB_SWIPE.ratio * fullHeight) return 'closed'; // 💨 hard swipe
83
+ return dy > AB_SWIPE.slop ? 'partial' : 'full'; // 🫳 gentle → S1 (a tap jitter stays at S2)
84
+ }
85
+ // ⬇️ from S1
86
+ if ((fast && velocity > 0) || dy > AB_SWIPE.ratio * partialHeight) return 'closed'; // 💨
87
+ if (returned && dy >= AB_SWIPE.secondSwipe) return 'closed'; // ✌️ the second swipe
88
+ return 'partial'; // 🧲 spring back
89
+ }
90
+
91
+ /** 📥 one release of a side-drawer swipe (edge swipe to open, or a swipe on the sheet to close) */
92
+ export interface AbSideReleaseInput {
93
+ distance: number; // ↔️ movement in the opening / closing direction (px, + = that way)
94
+ velocity: number; // ⚡ px/ms in that same direction
95
+ width: number; // 📏 the drawer width (320 left, 296 right)
96
+ }
97
+
98
+ /** ↔️ resolveAbSideRelease — does a side swipe commit? Past 30% of the width, or faster than 0.5px/ms that way. */
99
+ export function resolveAbSideRelease({ distance, velocity, width }: AbSideReleaseInput): boolean {
100
+ if (distance <= 0) return false; // 🚫 wrong way (or nowhere)
101
+ return distance > AB_SWIPE.ratio * width || velocity >= AB_SWIPE.velocity; // ✅
102
+ }
103
+
104
+ /** 🧱 isInAbEdgeZone — does a press at `x` start inside the `edge` zone of a box [left, right]? */
105
+ export function isInAbEdgeZone(x: number, edge: 'left' | 'right', box: { left: number; right: number }, standalone = false): boolean {
106
+ const inset = standalone ? AB_SWIPE.standaloneInset : 0; // 📱 iOS standalone: 16px in
107
+ const d = edge === 'left' ? x - box.left : box.right - x; // 📏 distance from that edge
108
+ return d >= inset && d <= inset + AB_SWIPE.edge; // 🎯
109
+ }
110
+
111
+ /** ⚡ a tiny velocity tracker: feed it samples, read px/ms over the last ~100ms */
112
+ export function createAbVelocityTracker(windowMs = 100): { add: (pos: number, t: number) => void; velocity: () => number; reset: () => void } {
113
+ let samples: Array<[number, number]> = []; // 🧺 [pos, time]
114
+ return {
115
+ add(pos, t) { samples.push([pos, t]); samples = samples.filter(([, ts]) => t - ts <= windowMs); }, // ➕ keep the window
116
+ velocity() {
117
+ if (samples.length < 2) return 0; // 🫥
118
+ const [p0, t0] = samples[0]; const [p1, t1] = samples[samples.length - 1]; // 📍 first / last
119
+ return t1 > t0 ? (p1 - p0) / (t1 - t0) : 0; // ⚡
120
+ },
121
+ reset() { samples = []; }, // 🧹
122
+ };
123
+ }
124
+
125
+ /** 🎠 isInAbHorizontalScroller — is `el` inside something that scrolls sideways (a code block, a carousel)?
126
+ * Edge swipes started there are ignored, so they never fight the user's horizontal scroll. */
127
+ export function isInAbHorizontalScroller(el: Element | null, stop?: Element | null): boolean {
128
+ for (let n = el; n && n !== stop && n !== document.documentElement; n = n.parentElement) {
129
+ if (n.closest('[data-ab-no-edge-swipe]') === n) return true; // 🙅 explicit opt-out
130
+ const ox = getComputedStyle(n).overflowX; // 🔎
131
+ if ((ox === 'auto' || ox === 'scroll') && n.scrollWidth > n.clientWidth) return true; // 🎠
132
+ }
133
+ return false;
134
+ }