ab-nextjs-components 0.1.14 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,38 @@
1
+ ## 0.2.0 (Unreleased, proposed)
2
+
3
+ Includes everything planned for 0.1.15, which is not released separately.
4
+
5
+ ### ⚠️ Heads-up (default changes, not breaking)
6
+
7
+ * ⚠️ **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.
8
+ * ⚠️ **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.
9
+
10
+ ### Drawers v2
11
+ - ✨ AbDrawer: `tier`, `swipe`, `snapPoints`/`defaultSnap`/`fullOnly`/`onSnapChange`, `handleLabels`, `centerIn="main"`, `initialFocus` selector, `returnFocus`, `closeIcon`, `headerStart` (all additive)
12
+ - ✨ Gesture kit: `AB_SWIPE`, `resolveAbSheetRelease`, `resolveAbSideRelease`, `isInAbEdgeZone`, `createAbVelocityTracker`, `useAbEdgeSwipe`
13
+ - ✨ New: AbSettingsDrawer, AbNavDrawer, AbTocDrawer, AbSearchDrawer (combobox/listbox, recents, grouped results), AbMobileHeader
14
+ - 🔥 Docs removed from examples; AbVersionSwitcher `label` defaults to ''
15
+ - 🐛 Initial focus no longer scrolls the layer; returnFocus takes the first visible match
16
+ - ♿ AbVersionSwitcher: with no `label`, the accessible name is `Version <version>`
17
+ - 🧯 AbSearchDrawer: a rejected or throwing `search` clears to "no results"; no stale results, no unhandled rejection
18
+ - 🆔 AbSearchDrawer: group heading ids are sanitised (`[A-Za-z0-9_-]`) and indexed, so they stay valid and unique
19
+ - 📌 AbMobileHeader needs ab-nextjs-core ≥ 0.2.1 with `mobileHeader="main"`
20
+ - 🤖 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.
21
+
22
+ ### From 0.1.15
23
+
24
+ * 🔎 **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.
25
+ * ⚠️ **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.
26
+ * 🏷️ **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".
27
+ * 🏷️ **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).
28
+ * 🧩 **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.
29
+ * 🏷️ **AbBottomDrawer title:** Mulish (`--ab-font-title`) 16/**800** (was 700). The bottom padding stays 16px + the safe area.
30
+ * 🔗 **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).
31
+ * ♿ **Inline AbLocaleSwitcher `ariaLabel`:** the group's accessible name. It defaults to `label`, whether the label is visible or hidden.
32
+ * 📱 **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.
33
+ * 📝 **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).
34
+ * ✂️ **AbAppBar compact pill:** a longer (translated) label ends in an ellipsis inside the 114px pill.
35
+
1
36
  ## [0.1.14](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.1.13...v0.1.14) (2026-10-20)
2
37
 
3
38
  * ⬆️ **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
151
  {brand && <div className={styles.abAppBarBrand}>{brand}</div>}
142
- {search && <div className={styles.abAppBarSearch}>{search}</div>}
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
+ }
@@ -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
+ }
@@ -45,7 +45,7 @@
45
45
  'use client';
46
46
 
47
47
  // ⚛️ React
48
- import { useCallback, useEffect, useId, useRef, useState, type CSSProperties, type ReactElement, type ReactNode } from 'react';
48
+ import { useCallback, useEffect, useId, useRef, useState, type CSSProperties, type PointerEvent as ReactPointerEvent, type ReactElement, type ReactNode } from 'react';
49
49
  // 🌀 portal into the scope's drawer layer
50
50
  import { createPortal } from 'react-dom';
51
51
  // 🧵 classes
@@ -57,10 +57,18 @@ import { AB_MOTION } from 'ab-nextjs-animations/motion';
57
57
  import 'ab-nextjs-animations/motion/styles.css';
58
58
  // 🎛️ the controller hook + scope type
59
59
  import { useAbDrawer, type AbDrawerScope, type UseAbDrawer } from './use-ab-drawer';
60
+ // 🤏 drawers v2: the pure swipe / snap rules
61
+ import { AB_SWIPE, createAbVelocityTracker, resolveAbSheetRelease, resolveAbSideRelease, type AbSheetSnap } from './gestures';
60
62
 
61
63
  // 📦 re-exports: one import for the whole drawer API
62
64
  export { useAbDrawer };
63
- export type { AbDrawerScope, UseAbDrawer };
65
+ export type { AbDrawerScope, UseAbDrawer, AbSheetSnap };
66
+ // 🤏 0.2.0: edge swipes + the pure rules, from the same entry
67
+ export { useAbEdgeSwipe, type UseAbEdgeSwipeOptions } from './use-ab-edge-swipe';
68
+ export { AB_SWIPE, resolveAbSheetRelease, resolveAbSideRelease } from './gestures';
69
+
70
+ /** 🥞 drawers v2 stacking tiers (spec z-order): aside (right) < nav (left) < sheet (bottom). Unset = the old single level. */
71
+ export type AbDrawerTier = 'aside' | 'nav' | 'sheet';
64
72
 
65
73
  /** 🧭 where it slides in from. `start` / `end` follow the writing direction (RTL-aware). */
66
74
  export type AbDrawerSide = 'top' | 'bottom' | 'left' | 'right' | 'start' | 'end';
@@ -81,7 +89,19 @@ export interface AbDrawerProps {
81
89
  modal?: boolean; // 🔒 trap focus + make the rest of the scope inert (default `true`)
82
90
  closeLabel?: string; // 🌍 default "Close"
83
91
  noJsFallback?: boolean; // 🧩 D41: without JS, render the content in flow (default `true`)
84
- initialFocus?: 'first' | 'panel'; // 🎯 on open: the first control (default) or the panel itself (no ring on the ✕; Tab then enters)
92
+ initialFocus?: 'first' | 'panel' | (string & {}); // 🎯 on open: the first control (default), the panel itself, or (0.2.0) a CSS selector inside the panel, e.g. `[role=radio][aria-checked=true]`
93
+ // 🆕 0.2.0 drawers v2 (John, God 01:22): all opt-in, the defaults keep the old drawer
94
+ tier?: AbDrawerTier; // 🥞 stacking tier: 'aside' (z 60) < 'nav' (61) < 'sheet' (62)
95
+ swipe?: boolean; // 🤏 side drawers: swipe the sheet back toward its edge to close (30% of the width or ≥ 0.5px/ms)
96
+ snapPoints?: boolean; // 🧲 bottom only, below 768px: snaps at 70% (S1) and full height (S2) with a handle; gestures per the spec
97
+ defaultSnap?: AbSheetSnap; // 🧲 where it opens (default 'partial'; e.g. 'full' for a search sheet)
98
+ fullOnly?: boolean; // 🧲 no 70% stop: opens at full height, a gentle drag springs back, a hard one closes (search: the keyboard is up)
99
+ onSnapChange?: (snap: AbSheetSnap) => void; // 🔔
100
+ handleLabels?: { expand: string; collapse: string }; // ♿ the handle button (default "Expand" / "Collapse")
101
+ centerIn?: 'main'; // 💻 bottom only, 768px and up: centred in the main pane, min(640px, main width) wide, ≤ 70% tall
102
+ returnFocus?: string; // ↩️ selector focused on close when there was no focusable opener (an edge swipe), e.g. the header logo link
103
+ closeIcon?: ReactNode; // ✕ the close glyph (default a text ✕)
104
+ headerStart?: ReactNode; // 🏷️ header content that does NOT label the dialog (e.g. a logo; then use `aria-label`). `title` wins
85
105
  className?: string; // 🏷️
86
106
  }
87
107
 
@@ -143,6 +163,7 @@ const reducedMotion = (): boolean => typeof window !== 'undefined' && typeof win
143
163
  */
144
164
  const AbDrawer = (props: AbDrawerProps): ReactElement => {
145
165
  const { open, onClose, scope = 'app', side = 'bottom', title, id, children, footer, size, modal = true, closeLabel = 'Close', noJsFallback = true, initialFocus = 'first', className } = props;
166
+ const { tier, swipe = false, snapPoints = false, defaultSnap = 'partial', onSnapChange, handleLabels, centerIn, returnFocus, closeIcon, headerStart, fullOnly = false } = props; // 🆕 0.2.0
146
167
  const auto = useId().replace(/[^A-Za-z0-9_-]/g, ''); // 🆔 SSR-stable
147
168
  const dialogId = id ?? `ab-drawer-${auto}`; // 🆔
148
169
  const titleId = `${dialogId}-title`; // 🏷️
@@ -201,14 +222,22 @@ const AbDrawer = (props: AbDrawerProps): ReactElement => {
201
222
  // ♿ focus in on open, back to the opener on close
202
223
  useEffect(() => {
203
224
  if (!open || !present || !panel.current) return;
204
- const first = initialFocus === 'panel' ? null : panel.current.querySelector<HTMLElement>(FOCUSABLE); // 🎯 first control, else the panel
225
+ const pick = initialFocus === 'panel' ? null : initialFocus === 'first' ? FOCUSABLE : initialFocus; // 🎯 0.2.0: or a selector
226
+ const first = pick ? panel.current.querySelector<HTMLElement>(pick) ?? (pick !== FOCUSABLE ? panel.current.querySelector<HTMLElement>(FOCUSABLE) : null) : null; // 🎯 that, else the first control, else the panel
227
+ // 👀 e.g. the checked language in view: scroll ONLY the drawer body (scrollIntoView would also scroll the clipped
228
+ // layer and undo the 70% snap offset, WebKit e2e 2026-10-21)
229
+ const body = panel.current.querySelector<HTMLElement>('[data-ab-part="drawer-body"]');
230
+ if (first && body && body.contains(first)) { const b = body.getBoundingClientRect(); const r = first.getBoundingClientRect(); if (r.bottom > b.bottom) body.scrollTop += r.bottom - b.bottom; else if (r.top < b.top) body.scrollTop -= b.top - r.top; }
205
231
  (first ?? panel.current).focus({ preventScroll: true });
206
232
  return () => {
207
- const back = opener.current as HTMLElement | null; // ↩️
233
+ const had = opener.current as HTMLElement | null; // ↩️
234
+ const usable = had && had !== document.body && had.isConnected ? had : null; // 🤏 a swipe has no opener
235
+ // ↩️ 0.2.0 fallback: the first VISIBLE match (an app often renders the logo twice, one hidden per breakpoint)
236
+ const back = usable ?? (returnFocus ? Array.from(document.querySelectorAll<HTMLElement>(returnFocus)).find((el) => el.getClientRects().length > 0) ?? null : null);
208
237
  // ⏭️ a microtask later: the inert cleanup below runs after this one, and an inert opener can't take focus
209
238
  queueMicrotask(() => { if (back && back.isConnected && typeof back.focus === 'function') back.focus({ preventScroll: true }); });
210
239
  };
211
- }, [open, present, layer, initialFocus]); // 🎯 initialFocus is static in practice
240
+ }, [open, present, layer, initialFocus, returnFocus]); // 🎯 static in practice
212
241
 
213
242
  // 🔒 the rest of the scope is inert while open (modal only); we only undo what we set
214
243
  useEffect(() => {
@@ -228,6 +257,117 @@ const AbDrawer = (props: AbDrawerProps): ReactElement => {
228
257
  return () => { const i = openStack.lastIndexOf(token); if (i >= 0) openStack.splice(i, 1); };
229
258
  }, [open, token]);
230
259
 
260
+ // 🧲 0.2.0: snap state (bottom + snapPoints, below 768px) and the laptop centring (centerIn="main", 768px and up)
261
+ const [mobile, setMobile] = useState(false); // 📱 below 768px?
262
+ const [snap, setSnapState] = useState<AbSheetSnap>(fullOnly ? 'full' : defaultSnap); // 🧲 S1 / S2
263
+ const [returned, setReturned] = useState(false); // ✌️ came back to S1 from S2 with a gentle drag
264
+ const [geo, setGeo] = useState<Record<string, string>>({}); // 📐 measured CSS vars (px)
265
+ const snapping = snapPoints && side === 'bottom' && mobile; // 🧲 live?
266
+ const centring = centerIn === 'main' && side === 'bottom' && !mobile; // 💻 live?
267
+ const setSnap = useCallback((next: AbSheetSnap) => { setSnapState(next); onSnapChange?.(next); }, [onSnapChange]);
268
+ // 🔁 every open starts at defaultSnap (derived during render, like `present`)
269
+ const [lastOpen, setLastOpen] = useState(open);
270
+ if (open !== lastOpen) { setLastOpen(open); if (open) { setSnapState(fullOnly ? 'full' : defaultSnap); setReturned(false); } }
271
+ // 📱 follow the 768px breakpoint (the same edge core uses)
272
+ useEffect(() => {
273
+ if (!(snapPoints || centerIn) || typeof window.matchMedia !== 'function') return;
274
+ const mq = window.matchMedia('(max-width: 767px)'); // 📱
275
+ const on = () => setMobile(mq.matches);
276
+ on(); mq.addEventListener?.('change', on);
277
+ return () => mq.removeEventListener?.('change', on);
278
+ }, [snapPoints, centerIn]);
279
+ // 📐 measure: S1 offset (100% − 70% of the app) and the main pane box inside the host
280
+ useEffect(() => {
281
+ const host = layer?.parentElement;
282
+ if (!present || !host || !(snapping || centring)) return;
283
+ const measure = () => {
284
+ const hb = host === document.body ? { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight } : host.getBoundingClientRect(); // 📏
285
+ const next: Record<string, string> = { '--ab-drawer-host-h': `${hb.height}px` };
286
+ if (snapping) {
287
+ const ph = panel.current?.getBoundingClientRect().height ?? hb.height; // 📏 the full-height sheet
288
+ next['--ab-drawer-partial-offset'] = `${Math.max(0, ph - 0.7 * hb.height)}px`; // 🧲 S1 = 70% of the app visible
289
+ }
290
+ if (centring) {
291
+ const main = host.querySelector<HTMLElement>('[data-ab-part="main"]')?.getBoundingClientRect(); // 📄 the main pane
292
+ next['--ab-drawer-main-left'] = `${main ? main.left - hb.left : 0}px`;
293
+ next['--ab-drawer-main-width'] = `${main ? main.width : hb.width}px`;
294
+ }
295
+ setGeo((g) => (JSON.stringify(g) === JSON.stringify(next) ? g : next)); // 🧮 no loop
296
+ };
297
+ measure();
298
+ const ro = typeof ResizeObserver === 'function' ? new ResizeObserver(measure) : null; // 👀 resizes
299
+ ro?.observe(host); if (panel.current) ro?.observe(panel.current);
300
+ return () => ro?.disconnect();
301
+ }, [present, layer, snapping, centring]);
302
+
303
+ // 🤏 0.2.0 drags: side sheets swipe toward their edge to close; the snap sheet follows the finger and resolves
304
+ const drag = useRef<{ x: number; y: number; t: number; axis: 0 | 1 | 2; v: ReturnType<typeof createAbVelocityTracker>; el?: Element; id?: number } | null>(null); // 0 = undecided, 1 = ours, 2 = not ours
305
+ const edgeSign = side === 'left' || side === 'start' ? -1 : side === 'right' || side === 'end' ? 1 : 0; // ⬅️ / ➡️ the closing direction
306
+ const setDragTransform = (value: string | null) => {
307
+ const el = panel.current; if (!el) return;
308
+ el.toggleAttribute('data-dragging', value != null); // 🫳 CSS drops the transition while the finger leads
309
+ if (value != null) el.style.removeProperty('--ab-motion-duration'); // 🧹 last release's speed must not beat the 0ms drag rule
310
+ if (value == null) el.style.removeProperty('transform'); else el.style.setProperty('transform', value);
311
+ };
312
+ const onDragStart = (e: { clientX: number; clientY: number; timeStamp: number }, from: 'grip' | 'body') => {
313
+ if (!(swipe && edgeSign !== 0) && !snapping) return; // 🙅 nothing to drag
314
+ if (from === 'body' && snapping && (panel.current?.querySelector('[data-ab-part="drawer-body"]')?.scrollTop ?? 0) > 0) return; // 📜 content not at the top: let it scroll
315
+ const v = createAbVelocityTracker(); v.add(snapping && edgeSign === 0 ? e.clientY : e.clientX, e.timeStamp);
316
+ drag.current = { x: e.clientX, y: e.clientY, t: e.timeStamp, axis: 0, v };
317
+ };
318
+ const onDragMove = (e: { clientX: number; clientY: number; timeStamp: number; preventDefault?: () => void; cancelable?: boolean }) => {
319
+ const d = drag.current; if (!d || d.axis === 2) return;
320
+ const dx = e.clientX - d.x; const dy = e.clientY - d.y; // ↔️ ↕️
321
+ const vertical = edgeSign === 0; // 🧲 the bottom sheet moves on y
322
+ if (d.axis === 0) {
323
+ if (Math.max(Math.abs(dx), Math.abs(dy)) < AB_SWIPE.slop) return; // 🫳 still a tap
324
+ const mine = vertical ? Math.abs(dy) > Math.abs(dx) : Math.abs(dx) > Math.abs(dy); // 🧭 our axis?
325
+ d.axis = mine ? 1 : 2; if (!mine) return;
326
+ if (d.el && d.id != null) d.el.setPointerCapture?.(d.id); // 📌 captured only once it IS a drag (taps on links still click)
327
+ }
328
+ if (e.cancelable) e.preventDefault?.(); // 🚫 no page scroll while we lead
329
+ d.v.add(vertical ? e.clientY : e.clientX, e.timeStamp); // ⚡
330
+ if (vertical) {
331
+ const base = snap === 'full' ? 0 : parseFloat(geo['--ab-drawer-partial-offset'] ?? '0'); // 🧲 where it rests
332
+ setDragTransform(`translateY(${Math.max(0, base + dy)}px)`); // ⬇️⬆️ follow (never above S2)
333
+ } else {
334
+ const along = dx * edgeSign; // ↔️ + = toward the edge
335
+ setDragTransform(`translateX(${Math.max(0, along) * edgeSign}px)`); // ↔️ follow, never past open
336
+ }
337
+ };
338
+ const onDragEnd = (e: { clientX: number; clientY: number; timeStamp: number }) => {
339
+ const d = drag.current; drag.current = null;
340
+ if (!d || d.axis !== 1) { setDragTransform(null); return; }
341
+ const vertical = edgeSign === 0;
342
+ const vel = d.v.velocity(); // ⚡ px/ms
343
+ setDragTransform(null); // 🛬 hand back to CSS (the attribute transition carries on)
344
+ if (!vertical) {
345
+ const dist = (e.clientX - d.x) * edgeSign; // ↔️ toward the edge
346
+ if (resolveAbSideRelease({ distance: dist, velocity: vel * edgeSign, width: panel.current?.offsetWidth ?? 320 })) close.current(); // ✅
347
+ return;
348
+ }
349
+ const hostH = parseFloat(geo['--ab-drawer-host-h'] ?? '0') || window.innerHeight; // 📏
350
+ const ph = panel.current?.offsetHeight || hostH; // 📏 S2 height
351
+ const resolved = resolveAbSheetRelease({ from: snap, dy: e.clientY - d.y, velocity: vel, partialHeight: 0.7 * hostH, fullHeight: ph, returned }); // 🧲
352
+ const to = fullOnly && resolved === 'partial' ? 'full' : resolved; // 🧲 fullOnly: no S1, spring back to S2
353
+ // ⏱️ carry the release speed: the remaining distance at that speed, between 120 and 240ms
354
+ const ms = Math.abs(vel) > 0.05 ? Math.round(Math.min(AB_DRAWER_DURATION, Math.max(120, (0.3 * hostH) / Math.abs(vel)))) : AB_DRAWER_DURATION;
355
+ panel.current?.style.setProperty('--ab-motion-duration', `${ms}ms`); // 🎞️ the ab-nextjs-animations token
356
+ if (to === 'closed') { close.current(); return; }
357
+ setReturned(snap === 'full' && to === 'partial'); // ✌️ remember the gentle return
358
+ if (to !== snap) setSnap(to);
359
+ };
360
+ // 🖐️ pointer handlers (touch / pen / mouse). The grip kind rides on `data-ab-grip`, so these are plain handlers
361
+ // (never called during render); the pointer is captured only once the press becomes a drag
362
+ const onGripDown = (e: ReactPointerEvent) => {
363
+ if (e.button !== 0) return;
364
+ onDragStart(e, (e.currentTarget as Element).getAttribute('data-ab-grip') === 'body' ? 'body' : 'grip');
365
+ if (drag.current) { drag.current.el = e.currentTarget as Element; drag.current.id = e.pointerId; } // 📌 for the capture
366
+ };
367
+ const onGripMove = (e: ReactPointerEvent) => onDragMove(e);
368
+ const onGripUp = (e: ReactPointerEvent) => onDragEnd(e);
369
+ const gripProps = { onPointerDown: onGripDown, onPointerMove: onGripMove, onPointerUp: onGripUp, onPointerCancel: onGripUp }; // 🖐️
370
+
231
371
  // ⎋ Escape closes (skips events an inner menu already handled); Tab stays inside (modal). Topmost drawer only
232
372
  const onKeyDown = useCallback((e: KeyboardEvent) => {
233
373
  if (!panel.current || !isTopDrawer(token)) return; // 🥞 a drawer under another one stays put
@@ -250,7 +390,10 @@ const AbDrawer = (props: AbDrawerProps): ReactElement => {
250
390
  const heading = title == null ? null : typeof title === 'string' || typeof title === 'number'
251
391
  ? <h2 id={titleId} className={styles.abDrawerTitle}>{title}</h2>
252
392
  : <div id={props['aria-labelledby'] ? undefined : titleId} className={styles.abDrawerTitle}>{title}</div>;
253
- const sizeVar = size ? ({ '--ab-drawer-size': size } as CSSProperties) : undefined; // 📏
393
+ const head = heading ?? (headerStart != null ? <div className={styles.abDrawerTitle} data-ab-part="drawer-header-start">{headerStart}</div> : null); // 🏷️ 0.2.0
394
+ const sizeVar = (size || snapping || centring ? { ...(size ? { '--ab-drawer-size': size } : {}), ...(snapping || centring ? geo : {}) } : undefined) as CSSProperties | undefined; // 📏 + 🧲 measured vars
395
+ const grip = snapping || (swipe && edgeSign !== 0); // 🤏 drags on
396
+ const handle = snapPoints && side === 'bottom'; // ➖ the handle strip
254
397
 
255
398
  // 🧩 D41: before hydration (and with no JS at all) the content is an in-flow section
256
399
  if (!layer) {
@@ -270,7 +413,7 @@ const AbDrawer = (props: AbDrawerProps): ReactElement => {
270
413
  return (
271
414
  <div ref={anchor} className={styles.abDrawerAnchor} data-ab-part="drawer-anchor">
272
415
  {present && createPortal(
273
- <div className={styles.abDrawerFrame} data-state={shown ? 'open' : 'closed'} data-side={side} data-scope={scope}>
416
+ <div className={styles.abDrawerFrame} data-state={shown ? 'open' : 'closed'} data-side={side} data-scope={scope} data-tier={tier}>
274
417
  {/* 🌫️ scrim: a click closes (pointer only; keyboard users have Escape and the close button) */}
275
418
  <div className={clsx(styles.abDrawerScrim, AB_MOTION.colors)} data-ab-part="drawer-scrim" aria-hidden="true" onClick={() => close.current()} />
276
419
  <div
@@ -284,15 +427,23 @@ const AbDrawer = (props: AbDrawerProps): ReactElement => {
284
427
  className={clsx('AbDrawer', styles.abDrawer, AB_MOTION.transform, className)}
285
428
  data-ab-part="drawer"
286
429
  data-side={side}
430
+ data-snap={snapping ? snap : undefined} // 🧲 0.2.0: CSS places S1 / S2
431
+ data-center={centring ? 'main' : undefined} // 💻 0.2.0: centred in the main pane
432
+ data-swipe={grip ? 'true' : undefined} // 🤏 touch-action hooks
287
433
  style={sizeVar}
434
+ {...(swipe && edgeSign !== 0 ? { ...gripProps, 'data-ab-grip': 'body' } : {})}
288
435
  >
289
- <div className={styles.abDrawerHeader}>
290
- {heading}
436
+ {handle && (snapping && !fullOnly ? (
437
+ // ➖ 0.2.0: the handle (40×4 bar in a 24px strip, 44px touch zone): a button that toggles S1 / S2
438
+ <button type="button" className={styles.abDrawerHandle} data-ab-part="drawer-handle" aria-expanded={snap === 'full'} aria-label={snap === 'full' ? handleLabels?.collapse ?? 'Collapse' : handleLabels?.expand ?? 'Expand'} onClick={() => { setReturned(false); setSnap(snap === 'full' ? 'partial' : 'full'); }} data-ab-grip="grip" {...gripProps} />
439
+ ) : <div className={styles.abDrawerHandle} data-ab-part="drawer-handle" aria-hidden="true" {...(snapping ? { ...gripProps, 'data-ab-grip': 'grip' } : {})} />)}
440
+ <div className={styles.abDrawerHeader} data-ab-part="drawer-header" {...(snapping ? { ...gripProps, 'data-ab-grip': 'grip' } : {})}>
441
+ {head}
291
442
  <button type="button" className={styles.abDrawerClose} data-ab-part="drawer-close" aria-label={closeLabel} onClick={() => close.current()}>
292
- <span aria-hidden="true">✕</span>
443
+ {closeIcon ?? <span aria-hidden="true">✕</span>}
293
444
  </button>
294
445
  </div>
295
- <div className={styles.abDrawerBody} data-ab-part="drawer-body">{children}</div>
446
+ <div className={styles.abDrawerBody} data-ab-part="drawer-body" {...(snapping ? { ...gripProps, 'data-ab-grip': 'body' } : {})}>{children}</div>
296
447
  {footer != null && <div className={styles.abDrawerFooter} data-ab-part="drawer-footer">{footer}</div>}
297
448
  </div>
298
449
  </div>,