ab-nextjs-components 0.1.13 → 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.
Files changed (62) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +35 -0
  3. package/ab-app-bar/index.tsx +53 -13
  4. package/ab-app-bar/styles.module.css +68 -4
  5. package/ab-bottom-drawer/index.tsx +71 -0
  6. package/ab-bottom-drawer/styles.module.css +66 -0
  7. package/ab-breadcrumbs/index.tsx +92 -0
  8. package/ab-breadcrumbs/styles.module.css +54 -0
  9. package/ab-button/helpers.ts +6 -1
  10. package/ab-button/index.tsx +8 -2
  11. package/ab-button/styles.module.css +39 -0
  12. package/ab-card/styles.module.css +1 -1
  13. package/ab-carousel/styles.module.css +1 -1
  14. package/ab-chip/index.tsx +16 -4
  15. package/ab-chip/styles.module.css +12 -1
  16. package/ab-confirm-drawer/index.tsx +97 -0
  17. package/ab-confirm-drawer/styles.module.css +41 -0
  18. package/ab-drawer/gestures.ts +134 -0
  19. package/ab-drawer/index.tsx +458 -0
  20. package/ab-drawer/kit.module.css +204 -0
  21. package/ab-drawer/styles.module.css +166 -0
  22. package/ab-drawer/use-ab-drawer.ts +89 -0
  23. package/ab-drawer/use-ab-edge-swipe.ts +155 -0
  24. package/ab-drawer-list/index.tsx +118 -0
  25. package/ab-drawer-list/styles.module.css +65 -0
  26. package/ab-flow-diagram/styles.module.css +2 -2
  27. package/ab-icon/builtin.ts +4 -0
  28. package/ab-icon-button/index.tsx +13 -2
  29. package/ab-icon-button/styles.module.css +1 -1
  30. package/ab-install-snippet/index.tsx +51 -29
  31. package/ab-install-snippet/styles.module.css +34 -2
  32. package/ab-kbd/styles.module.css +1 -1
  33. package/ab-list/index.tsx +107 -0
  34. package/ab-list/styles.module.css +82 -0
  35. package/ab-locale-switcher/index.tsx +103 -10
  36. package/ab-locale-switcher/styles.module.css +24 -4
  37. package/ab-mobile-header/index.tsx +100 -0
  38. package/ab-nav-drawer/index.tsx +158 -0
  39. package/ab-navbar/index.tsx +1 -1
  40. package/ab-navbar/styles.module.css +20 -2
  41. package/ab-navbar/view.tsx +7 -4
  42. package/ab-package-card/index.tsx +49 -2
  43. package/ab-package-card/styles.module.css +40 -0
  44. package/ab-search-drawer/index.tsx +279 -0
  45. package/ab-search-trigger/index.tsx +22 -2
  46. package/ab-search-trigger/styles.module.css +30 -1
  47. package/ab-settings-drawer/index.tsx +160 -0
  48. package/ab-sidebar/index.tsx +6 -3
  49. package/ab-sidebar/styles.module.css +53 -5
  50. package/ab-sidebar/view.tsx +18 -4
  51. package/ab-theme-toggle/index.tsx +21 -6
  52. package/ab-theme-toggle/styles.module.css +18 -3
  53. package/ab-toc/index.tsx +9 -2
  54. package/ab-toc/styles.module.css +20 -8
  55. package/ab-toc-drawer/index.tsx +129 -0
  56. package/ab-version-switcher/index.tsx +143 -0
  57. package/ab-version-switcher/styles.module.css +76 -0
  58. package/index.ts +50 -0
  59. package/package.json +28 -3
  60. package/server/ab-button/index.tsx +6 -2
  61. package/server/ab-button/styles.module.css +39 -0
  62. package/types/index.d.ts +37 -0
@@ -40,9 +40,20 @@
40
40
  */
41
41
 
42
42
  // ⚛️ React
43
- import type { ReactElement, ReactNode } from 'react';
43
+ import type { CSSProperties, ReactElement, ReactNode } from 'react';
44
+ // 🧵 classes
45
+ import clsx from 'clsx';
44
46
  // 🃏 base card
45
47
  import AbCard from '../ab-card';
48
+ // 🔗 G42 link
49
+ import Link from '../ab-link';
50
+ // 🏷️ footer chips (0.1.14)
51
+ import AbChip from '../ab-chip';
52
+ // 🔣 trailing arrow
53
+ import AbIcon from '../ab-icon';
54
+ // 🎬 motion classes (ab-nextjs-animations ≥ 0.2.4)
55
+ import { AB_MOTION } from 'ab-nextjs-animations/motion';
56
+ import 'ab-nextjs-animations/motion/styles.css';
46
57
  // 🎨 styles
47
58
  import styles from './styles.module.css';
48
59
 
@@ -59,6 +70,11 @@ export interface AbPackageCardProps {
59
70
  tags?: string[]; // 🏷️ e.g. ['client', 'server']
60
71
  headingLevel?: 2 | 3 | 4; // ♿
61
72
  className?: string; // 🏷️
73
+ // 🏠 0.1.14 (P10, Home spec §4 package card). Passing `preview` or `title` switches to the Home layout:
74
+ // 56px preview tile · 30px icon tile + display title + mono name · clamped description · chips + →
75
+ preview?: ReactNode; // 🖼️ decorative preview tile content (Aa Aa Aa, swatches, a curve…), aria-hidden
76
+ title?: ReactNode; // 🏷️ display name (e.g. "Fonts"); `name` becomes the mono subtitle
77
+ descriptionLines?: number; // ✂️ clamp the description (Home: 2)
62
78
  }
63
79
 
64
80
  /**
@@ -70,7 +86,38 @@ export function toAbPackageNameParts(name: string): ReactNode[] {
70
86
  }
71
87
 
72
88
  /** 📦 AbPackageCard (G45): a package tile on AbCard (one link, 2px lift on laptop+, none when reduced). */
73
- const AbPackageCard = ({ name, href, description, version, icon, media, id, badge, tags, headingLevel, className }: AbPackageCardProps): ReactElement => (
89
+ const AbPackageCard = (props: AbPackageCardProps): ReactElement => (props.preview != null || props.title != null ? <AbPackageCardHome {...props} /> : <AbPackageCardLegacy {...props} />);
90
+
91
+ /** 🏠 0.1.14 (P10): the Home layout. One link (the title, stretched over the card), focus ring on the card. */
92
+ function AbPackageCardHome({ name, href, description, version, icon, media, id, badge, tags, headingLevel = 3, className, preview, title, descriptionLines }: AbPackageCardProps): ReactElement {
93
+ const H = `h${headingLevel}` as 'h2' | 'h3' | 'h4'; // ♿
94
+ const clamp = descriptionLines ? ({ '--ab-package-card-lines': descriptionLines } as CSSProperties) : undefined; // ✂️
95
+ return (
96
+ <article id={id} className={clsx('AbPackageCard', styles.home, AB_MOTION.interactive, className)} data-ab-part="package-card" data-variant="home">
97
+ {preview != null && <div className={styles.homePreview} aria-hidden="true">{preview}</div> /* 🖼️ decorative */}
98
+ <div className={styles.homeHead}>
99
+ {(media ?? icon) != null && <span className={styles.homeIcon} aria-hidden="true">{media ?? icon}</span>}
100
+ <div className={styles.homeTitles}>
101
+ <H className={styles.homeTitle}><Link href={href} className={styles.homeLink}>{title ?? name}</Link></H>
102
+ {title != null && <code className={styles.homeName}>{name}</code> /* ⌨️ the npm name */}
103
+ </div>
104
+ {badge != null && <span className={styles.homeBadge}>{badge}</span>}
105
+ </div>
106
+ {description != null && <p className={styles.homeDesc} data-clamp={descriptionLines ? 'true' : undefined} style={clamp}>{description}</p>}
107
+ {(version || tags?.length) ? (
108
+ <div className={styles.homeFoot}>
109
+ {version && <AbChip size="sm" shape="rounded" mono tone="accent">v{version}</AbChip>}
110
+ {tags?.map((t) => <AbChip key={t} size="sm" shape="rounded" mono tone="sage" className={styles.homeTag}>{t}</AbChip>)}
111
+ <span className={styles.homeGrow} />
112
+ <AbIcon name="arrow_forward" size={16} className={styles.homeGo} />
113
+ </div>
114
+ ) : null}
115
+ </article>
116
+ );
117
+ }
118
+
119
+ /** 🕰️ ≤ 0.1.13 layout on AbCard. */
120
+ const AbPackageCardLegacy = ({ name, href, description, version, icon, media, id, badge, tags, headingLevel, className }: AbPackageCardProps): ReactElement => (
74
121
  <AbCard
75
122
  id={id}
76
123
  className={className}
@@ -39,3 +39,43 @@
39
39
  .abPackageCardName { font-family: var(--ab-font-code, var(--ab-font-mono, ui-monospace, monospace)); font-size: 16px; overflow-wrap: anywhere; word-break: normal; hyphens: none; display: block; min-width: 0; max-width: 100%; } /* 📦 0.1.13 (Joseph): wraps at the <wbr> after a hyphen first (ab-nextjs-/components); `anywhere` only splits a part that alone is wider than a very narrow card (animations at ~70px), so it never overflows */
40
40
  .abPackageCardVersion { font-family: var(--ab-font-code, var(--ab-font-mono, ui-monospace, monospace)); opacity: 0.8; } /* 🏷️ */
41
41
  .abPackageCardTag { padding: 0 8px; border-radius: 999px; line-height: 20px; background: var(--ab-color-surface-container-high, rgb(0 0 0 / 0.06)); } /* 🏷️ */
42
+
43
+ /* ===== 🏠 0.1.14 (P10, Home spec §4 package card) ===== */
44
+ .home {
45
+ position: relative; display: flex; flex-direction: column; min-width: 0; box-sizing: border-box; /* 📐 */
46
+ padding: 10px 10px 12px; border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); border-radius: var(--ab-radius-card, 14px); /* 🔲 */
47
+ background: var(--ab-color-card, #fff); color: var(--ab-color-text, #211a16); box-shadow: var(--ab-shadow-card, 0 1px 2px rgb(33 26 22 / 0.05)); /* 🎨 */
48
+ /* 🎞️ the fade + lift timing comes from ab-nextjs-animations (.ab-motion-interactive on the element) */
49
+ }
50
+ .home:hover { border-color: color-mix(in srgb, var(--ab-color-accent, #a67c52) 40%, transparent); transform: translateY(-1px); } /* 🖱️ */
51
+ .home:has(.homeLink:focus-visible) { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; } /* ♿ ring on the card */
52
+ .homeLink { color: inherit; text-decoration: none; outline: none; } /* 🔗 */
53
+ .homeLink::after { content: ''; position: absolute; inset: 0; border-radius: inherit; } /* 🖱️ the whole card clicks */
54
+ .homePreview {
55
+ height: 56px; border-radius: var(--ab-radius-tile, 9px); background: var(--ab-color-card2, #fbf3ec); /* 🖼️ */
56
+ display: flex; align-items: center; justify-content: center; gap: 10px; overflow: hidden; color: var(--ab-color-accent-text, #88603d);
57
+ }
58
+ .homeHead { display: flex; align-items: center; gap: 9px; margin-top: 11px; padding: 0 2px; min-width: 0; } /* 📐 */
59
+ .homeIcon {
60
+ flex: none; width: 30px; height: 30px; border-radius: var(--ab-radius-row, 8px); /* 🔲 */
61
+ background: var(--ab-color-tint, #f4e7db); color: var(--ab-color-accent-text, #88603d); display: flex; align-items: center; justify-content: center;
62
+ }
63
+ .homeIcon svg { width: 18px; height: 18px; } /* 🔣 */
64
+ .homeTitles { min-width: 0; } /* ✂️ */
65
+ .homeTitle { margin: 0; font-family: var(--ab-font-title, inherit); font-size: 14px; font-weight: 800; line-height: 1.2; letter-spacing: -0.005em; } /* 🏷️ Mulish */
66
+ .homeName { display: block; margin-top: 1px; font: 400 11px/1.3 var(--ab-font-code, ui-monospace, monospace); color: var(--ab-color-faint, #807062); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } /* ⌨️ */
67
+ .homeBadge { margin-inline-start: auto; flex: none; } /* 🔴 */
68
+ .homeDesc { margin: 8px 0 0; padding: 0 2px; font-size: 12.5px; line-height: 1.45; color: var(--ab-color-muted, #6b5b50); min-height: 36px; } /* 📝 */
69
+ .homeDesc[data-clamp='true'] { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: var(--ab-package-card-lines, 2); line-clamp: var(--ab-package-card-lines, 2); overflow: hidden; } /* ✂️ */
70
+ .homeFoot { display: flex; align-items: center; margin-top: 10px; padding: 0 2px; } /* 🏷️ */
71
+ .homeTag { margin-inline-start: 6px; } /* 🌿 */
72
+ .homeGrow { flex: 1; } /* ↔️ */
73
+ .homeGo { width: 16px; height: 16px; color: var(--ab-color-faint, #807062); } /* → */
74
+ @media (max-width: 767px) {
75
+ .home { padding: 8px 8px 10px; border-radius: 13px; } /* 📱 */
76
+ .homePreview { height: 44px; }
77
+ .homeHead { margin-top: 9px; }
78
+ .homeDesc { margin-top: 6px; font-size: 12px; }
79
+ .homeFoot { margin-top: 8px; }
80
+ }
81
+ @media (prefers-reduced-motion: reduce) { .home:hover { transform: none; } } /* ♿ no lift */
@@ -0,0 +1,279 @@
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: AbSearchDrawer
28
+ * @file: ab-search-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
+ * -|> <AbSearchTrigger variant="field" label="Search…" onOpen={() => setOpen(true)} hotkey={false} />
35
+ * -|> <AbSearchDrawer open={open} onClose={() => setOpen(false)} search={(q) => index.query(q)} />
36
+ */
37
+
38
+ /*
39
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40
+ * MOTTO: We'll always do more 😜!!!
41
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
42
+ */
43
+
44
+
45
+ 'use client';
46
+
47
+ // ⚛️ React
48
+ import { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
49
+ // 🧵 classes
50
+ import clsx from 'clsx';
51
+ // 🗄️ the drawer (fullOnly sheet on mobile, centred on laptop)
52
+ import AbDrawer from '../ab-drawer';
53
+ // 🔣 icons
54
+ import AbIcon from '../ab-icon';
55
+ // 🔗 the app's link
56
+ import Link from '../ab-link';
57
+ // 🎨 the drawers v2 kit
58
+ import kit from '../ab-drawer/kit.module.css';
59
+
60
+ /** 🔎 one result row */
61
+ export interface AbSearchDrawerItem {
62
+ id: string; // 🆔 unique across all groups
63
+ href: string; // 🔗 where it opens
64
+ title: string; // 🏷️ e.g. "AbButton"
65
+ description?: string; // 📝 one line (ellipsis)
66
+ meta?: string; // 🏷️ mono, e.g. "v0.2.x"
67
+ icon?: string; // 🔣 the 32px tile's AbIcons name
68
+ }
69
+ /** 📦 results grouped by package */
70
+ export interface AbSearchDrawerGroup { id: string; label: string; meta?: string; items: readonly AbSearchDrawerItem[] } // 🏷️ "Components" + "ab-nextjs-components"
71
+
72
+ /** 🌍 strings (English defaults) */
73
+ export interface AbSearchDrawerLabels {
74
+ title?: string; // "Search"
75
+ close?: string; // "Close search"
76
+ placeholder?: string; // "Search packages, components, hooks…"
77
+ clear?: string; // "Clear search"
78
+ recent?: string; // "Recent"
79
+ remove?: (term: string) => string; // "Remove <term>"
80
+ results?: (n: number) => string; // "4 results"
81
+ noResults?: string; // "No results"
82
+ noResultsFor?: (q: string) => ReactNode; // No results for “q”
83
+ hint?: ReactNode; // the line under it
84
+ didYouMean?: string; // "Did you mean"
85
+ }
86
+
87
+ /** ⚙️ props */
88
+ export interface AbSearchDrawerProps {
89
+ open: boolean; // 🚪
90
+ onClose: () => void; // ⎋
91
+ search: (query: string) => readonly AbSearchDrawerGroup[] | Promise<readonly AbSearchDrawerGroup[]>; // 🔎 called 150ms after typing stops, from 2 characters
92
+ suggest?: (query: string) => string | null | undefined; // 💡 the "Did you mean …?" term on no results
93
+ onOpenResult?: (item: AbSearchDrawerItem) => void; // 🔔 after a result is chosen (the link still navigates; the drawer closes)
94
+ defaultQuery?: string; // 🌱 the query on open (default '')
95
+ recentKey?: string | null; // 🕘 localStorage key (default `ab:search:recent`; null = no recents)
96
+ recentLimit?: number; // 🕘 default 4
97
+ recentWhen?: 'always' | 'empty'; // 🕘 'always' = above the results (John's frames, default); 'empty' = only with no query
98
+ labels?: AbSearchDrawerLabels; // 🌍
99
+ returnFocus?: string; // ↩️
100
+ id?: string; // 🆔
101
+ className?: string; // 🏷️
102
+ }
103
+
104
+ // 🕘 recents in localStorage: newest first, de-duplicated, capped
105
+ export const AB_SEARCH_RECENT_KEY = 'ab:search:recent';
106
+ const readRecent = (key: string | null): string[] => {
107
+ if (!key || typeof localStorage === 'undefined') return [];
108
+ try { const v = JSON.parse(localStorage.getItem(key) ?? '[]'); return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []; } catch { return []; } // 🧯 bad JSON = none
109
+ };
110
+ const writeRecent = (key: string | null, list: string[]) => { if (key && typeof localStorage !== 'undefined') try { localStorage.setItem(key, JSON.stringify(list)); } catch { /* 🧯 private mode */ } };
111
+ /** 🕘 addAbSearchRecent — the next recents list: `term` first, no duplicates (case-insensitive), at most `limit` */
112
+ export function addAbSearchRecent(list: readonly string[], term: string, limit = 4): string[] {
113
+ const t = term.trim(); if (!t) return [...list];
114
+ return [t, ...list.filter((x) => x.toLowerCase() !== t.toLowerCase())].slice(0, limit);
115
+ }
116
+
117
+ /** 🖍️ highlightAbSearch — wrap every case-insensitive match of `q` in `<mark>` (bronze 700 via the kit) */
118
+ export function highlightAbSearch(text: string, q: string): ReactNode {
119
+ const needle = q.trim(); if (needle.length < 2) return text;
120
+ const out: ReactNode[] = []; const lower = text.toLowerCase(); const n = needle.toLowerCase();
121
+ let i = 0; let k = 0;
122
+ for (let j = lower.indexOf(n); j >= 0; j = lower.indexOf(n, i)) {
123
+ if (j > i) out.push(text.slice(i, j));
124
+ out.push(<mark key={k++} className={kit.mark}>{text.slice(j, j + n.length)}</mark>); i = j + n.length;
125
+ }
126
+ if (i < text.length) out.push(text.slice(i));
127
+ return out.length ? out : text;
128
+ }
129
+
130
+ /**
131
+ * 🔎 AbSearchDrawer — John's search drawer (drawers v2 §4), a bottom-drawer variant.
132
+ *
133
+ * - 📱 below 768px: straight to full height (no 70% stop: the keyboard is up); a hard swipe down closes
134
+ * - 💻 768px and up: centred in the main pane, min(640px, main width), 70% tall; results scroll inside with a 48px fade
135
+ * - ⌨️ no shortcut key: open it from the Search tab / the search field (AbSearchTrigger `onOpen` + `hotkey={false}`)
136
+ * - 🔤 48px input (2px bronze border), autofocused; a 40px clear button keeps focus in the input
137
+ * - 🕘 up to 4 recent searches (localStorage `ab:search:recent`), saved on Enter or when a result opens; each removable
138
+ * - 📦 results after a 150ms debounce from 2 characters, grouped by package; matches in a bronze `<mark>`
139
+ * - ♿ combobox (aria-expanded / -controls / -autocomplete="list" / -activedescendant) + listbox with labelled groups
140
+ * and options; ↑/↓ wrap across groups, Enter opens the active (else the first) result, Esc clears then closes;
141
+ * a polite live region says "4 results" / "No results"
142
+ */
143
+ const AbSearchDrawer = ({ open, onClose, search, suggest, onOpenResult, defaultQuery = '', recentKey = AB_SEARCH_RECENT_KEY, recentLimit = 4, recentWhen = 'always', labels = {}, returnFocus, id, className }: AbSearchDrawerProps): ReactElement => {
144
+ const L = {
145
+ title: 'Search', close: 'Close search', placeholder: 'Search packages, components, hooks…', clear: 'Clear search', recent: 'Recent',
146
+ remove: (t: string) => `Remove ${t}`, results: (n: number) => `${n} result${n === 1 ? '' : 's'}`, noResults: 'No results',
147
+ noResultsFor: (q: string) => <>No results for “{q}”</>, didYouMean: 'Did you mean',
148
+ hint: <>Check the spelling or try a package name like <code>components</code> or <code>hooks</code>.</>, ...labels,
149
+ }; // 🌍
150
+ const auto = useId().replace(/[^A-Za-z0-9_-]/g, ''); // 🆔
151
+ const base = id ?? `ab-search-${auto}`;
152
+ // 🆔 James P2: group ids come from app data ("@scope/pkg", "a b"); keep only id-safe characters, and the index keeps them unique
153
+ const groupId = (g: AbSearchDrawerGroup, i: number) => `${base}-g-${i}-${String(g.id).replace(/[^A-Za-z0-9_-]/g, '_')}`;
154
+ const input = useRef<HTMLInputElement>(null); // 🔤
155
+ const list = useRef<HTMLDivElement>(null); // 📜
156
+ const [query, setQuery] = useState(defaultQuery); // 🔤
157
+ const [groups, setGroups] = useState<readonly AbSearchDrawerGroup[] | null>(null); // 📦 null = not searched (or < 2 chars)
158
+ const [active, setActive] = useState(0); // 🎯 index in the flat option list (-1 = none)
159
+ const [recent, setRecent] = useState<string[]>([]); // 🕘
160
+ const latest = useRef(search); // 🔁
161
+ useEffect(() => { latest.current = search; }, [search]);
162
+
163
+ // 🌱 each open: the default query, fresh recents
164
+ const [wasOpen, setWasOpen] = useState(false);
165
+ if (open !== wasOpen) { setWasOpen(open); if (open) { setQuery(defaultQuery); setRecent(readRecent(recentKey)); } }
166
+
167
+ // ⏱️ 150ms debounce, from 2 characters; stale answers are dropped
168
+ useEffect(() => {
169
+ const q = query.trim();
170
+ if (!open || q.length < 2) { const t = setTimeout(() => setGroups(null), 0); return () => clearTimeout(t); } // 🫥
171
+ let live = true;
172
+ const t = setTimeout(() => {
173
+ Promise.resolve().then(() => latest.current(q)) // 🧯 a sync throw becomes a rejection too
174
+ .then((g) => { if (live) { setGroups(g); setActive(g.some((x) => x.items.length) ? 0 : -1); } })
175
+ .catch(() => { if (live) { setGroups([]); setActive(-1); } }); // 🧯 James P2: a failed search shows "no results", never the previous query's results
176
+ }, 150);
177
+ return () => { live = false; clearTimeout(t); };
178
+ }, [query, open]);
179
+
180
+ const flat = useMemo(() => (groups ?? []).flatMap((g) => g.items), [groups]); // 📋 the option order
181
+ const starts = useMemo(() => { const m: Record<string, number> = {}; let n = 0; for (const g of groups ?? []) { m[g.id] = n; n += g.items.length; } return m; }, [groups]); // 🔢 each group's first option index
182
+ const optId = (i: number) => `${base}-opt-${i}`; // 🆔
183
+ const showRecent = recentKey !== null && recent.length > 0 && (recentWhen === 'always' ? !(groups && flat.length === 0) : query.trim() === ''); // 🕘
184
+ const expanded = flat.length > 0; // ♿ the listbox has options
185
+ const saveRecent = (term: string) => { const next = addAbSearchRecent(recent, term, recentLimit); setRecent(next); writeRecent(recentKey, next); }; // 🕘
186
+ const removeRecent = (term: string) => { const next = recent.filter((x) => x !== term); setRecent(next); writeRecent(recentKey, next); input.current?.focus(); };
187
+ const choose = (item: AbSearchDrawerItem) => { saveRecent(query); onOpenResult?.(item); onClose(); }; // 🔗
188
+
189
+ // ⌨️ the combobox keys (focus stays in the input)
190
+ const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
191
+ if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
192
+ if (!flat.length) return; e.preventDefault();
193
+ const n = e.key === 'ArrowDown' ? (active + 1) % flat.length : (active - 1 + flat.length) % flat.length; // 🔁 wraps across groups
194
+ setActive(n);
195
+ const el = document.getElementById(optId(n)); const box = list.current; // 👀 keep it in view, scrolling only the results
196
+ if (el && box) { const b = box.getBoundingClientRect(); const r = el.getBoundingClientRect(); if (r.bottom > b.bottom) box.scrollTop += r.bottom - b.bottom; else if (r.top < b.top) box.scrollTop -= b.top - r.top; }
197
+ } else if (e.key === 'Enter') {
198
+ e.preventDefault(); if (query.trim()) saveRecent(query); // 🕘
199
+ const i = active >= 0 ? active : 0; if (flat[i]) document.getElementById(optId(i))?.click(); // 🔗 the active, else the first
200
+ } else if (e.key === 'Escape' && query) {
201
+ e.preventDefault(); setQuery(''); // ⎋ first press clears (AbDrawer skips handled Escapes), the second closes
202
+ }
203
+ };
204
+
205
+ const none = groups !== null && flat.length === 0; // 🫥
206
+ const tip = suggest && none ? suggest(query.trim()) : null; // 💡
207
+ return (
208
+ <AbDrawer
209
+ open={open} onClose={onClose} id={id} side="bottom" scope="app" tier="sheet"
210
+ snapPoints fullOnly centerIn="main" title={L.title} closeLabel={L.close} closeIcon={<AbIcon name="close" size={24} />}
211
+ initialFocus="input" returnFocus={returnFocus}
212
+ className={clsx('AbSearchDrawer', kit.sheet, kit.searchSheet, className)}
213
+ >
214
+ <div className={kit.searchBody}>
215
+ <div className={kit.field}>
216
+ <AbIcon name="search" size={22} />
217
+ <input
218
+ ref={input} type="search" className={kit.input} value={query} placeholder={L.placeholder} aria-label={L.title}
219
+ role="combobox" aria-expanded={expanded} aria-controls={`${base}-list`} aria-autocomplete="list"
220
+ aria-activedescendant={expanded && active >= 0 ? optId(active) : undefined}
221
+ autoComplete="off" autoCorrect="off" spellCheck={false} enterKeyHint="search"
222
+ onChange={(e) => setQuery(e.target.value)} onKeyDown={onKey}
223
+ />
224
+ {query && <button type="button" className={kit.iconSm} aria-label={L.clear} onClick={() => { setQuery(''); input.current?.focus(); }}><AbIcon name="close" size={20} /></button>}
225
+ </div>
226
+ <div className={kit.resWrap}>
227
+ <div ref={list} className={kit.results} data-ab-part="search-results">
228
+ {showRecent && (
229
+ <>
230
+ <p className={kit.lbl} id={`${base}-recent`}>{L.recent}</p>
231
+ <ul className={kit.list} aria-labelledby={`${base}-recent`}>
232
+ {recent.map((t) => (
233
+ <li key={t} className={clsx(kit.row, kit.recent)}>
234
+ <AbIcon name="history" size={24} />
235
+ <button type="button" className={kit.recentGo} onClick={() => { setQuery(t); input.current?.focus(); }}>{t}</button>
236
+ <button type="button" className={kit.iconSm} aria-label={L.remove(t)} onClick={() => removeRecent(t)}><AbIcon name="close" size={20} /></button>
237
+ </li>
238
+ ))}
239
+ </ul>
240
+ {flat.length > 0 && <hr className={kit.hr} />}
241
+ </>
242
+ )}
243
+ <div id={`${base}-list`} role="listbox" aria-label={L.title} hidden={!expanded}>
244
+ {(groups ?? []).filter((g) => g.items.length).map((g, gi) => (
245
+ <div key={g.id} role="group" aria-labelledby={groupId(g, gi)}>
246
+ <p className={kit.grp2} id={groupId(g, gi)}><span>{g.label}</span>{g.meta && <code>{g.meta}</code>}</p>
247
+ {g.items.map((it, j) => {
248
+ const i = starts[g.id] + j; const on = i === active; // 🎯
249
+ return (
250
+ <Link key={it.id} id={optId(i)} href={it.href} role="option" aria-selected={on} tabIndex={-1} className={kit.sr} onClick={() => choose(it)} onMouseMove={() => { if (!on) setActive(i); }}>
251
+ <span className={kit.pkgIc} aria-hidden="true">{it.icon && <AbIcon name={it.icon} size={20} />}</span>
252
+ <span className={kit.srText}><b>{highlightAbSearch(it.title, query)}</b>{it.description && <small>{highlightAbSearch(it.description, query)}</small>}</span>
253
+ {it.meta && <code className={kit.srMeta}>{it.meta}</code>}
254
+ </Link>
255
+ );
256
+ })}
257
+ </div>
258
+ ))}
259
+ </div>
260
+ {none && (
261
+ <div className={kit.nores} data-ab-part="search-empty">
262
+ <span className={kit.pkgIc} aria-hidden="true"><AbIcon name="search" size={28} /></span>
263
+ <b>{L.noResultsFor(query.trim())}</b>
264
+ <p>{L.hint}</p>
265
+ {tip && <button type="button" className={clsx(kit.row, kit.didYouMean)} onClick={() => { setQuery(tip); input.current?.focus(); }}>{L.didYouMean}&nbsp;<mark className={kit.mark}>{tip}</mark>?</button>}
266
+ </div>
267
+ )}
268
+ </div>
269
+ <div className={kit.resFade} aria-hidden="true" />
270
+ </div>
271
+ <p className={kit.srOnly} role="status" aria-live="polite">{groups === null ? '' : none ? L.noResults : L.results(flat.length)}</p>
272
+ </div>
273
+ </AbDrawer>
274
+ );
275
+ };
276
+
277
+ // 📦 exports
278
+ export default AbSearchDrawer;
279
+ export { AbSearchDrawer };
@@ -63,6 +63,11 @@ export interface AbSearchTriggerProps {
63
63
  compact?: boolean; // 📱 icon-only pill (the label stays for screen readers), e.g. the mobile app bar
64
64
  comingSoon?: boolean; // 🚧 visible but inert: aria-disabled, no hotkey
65
65
  comingSoonLabel?: string; // 🏷️ default "Coming soon"
66
+ variant?: 'pill' | 'field'; // 🔎 0.1.14 (P6): 'field' = the Home 300×36 bordered field (default 'pill', the legacy look)
67
+ /** 📱 0.1.15 (God 00:08): a shorter label (e.g. "Search") that a compact AbAppBar shows below 768px instead of `label`
68
+ * (CSS picks; only one is ever displayed, so the accessible name stays single). Home field only. */
69
+ compactLabel?: string;
70
+ size?: 'md' | 'sm'; // 📱 0.1.14 (P6): 'sm' = the mobile 34px "Search ⌘K" pill (label + key cap stay visible)
66
71
  className?: string; // 🏷️
67
72
  }
68
73
 
@@ -80,7 +85,7 @@ export function isAbApplePlatform(nav?: { platform?: string; userAgent?: string;
80
85
  * announces `aria-keyshortcuts="Meta+K Control+K"`, and falls back to a link when there's no `onOpen`.
81
86
  * Note: the hotkey is a local listener; G48 `useAbHotkey` is deliberately not in hooks 0.1.7.
82
87
  */
83
- const AbSearchTrigger = ({ label = 'Search', onOpen, href, hotkey, shortcut, compact = false, comingSoon = false, comingSoonLabel = 'Coming soon', className }: AbSearchTriggerProps): ReactElement => {
88
+ const AbSearchTrigger = ({ label = 'Search', onOpen, href, hotkey, shortcut, compact = false, comingSoon = false, comingSoonLabel = 'Coming soon', compactLabel, variant = 'pill', size = 'md', className }: AbSearchTriggerProps): ReactElement => {
84
89
  // 🍎 SSR renders "Ctrl"; hydration then reads the platform (useSyncExternalStore: no mismatch, no effect)
85
90
  const apple = useSyncExternalStore(
86
91
  noopSubscribe, // 🔕 the platform never changes
@@ -101,8 +106,20 @@ const AbSearchTrigger = ({ label = 'Search', onOpen, href, hotkey, shortcut, com
101
106
  return () => window.removeEventListener('keydown', onKey); // 🧹
102
107
  }, [listen, onOpen]);
103
108
 
109
+ // 🏠 P6: the Home looks (field / sm pill) show ONE key cap ("⌘ K" / "⌘K") and keep "coming soon" out of the field
110
+ const home = variant === 'field' || size === 'sm';
111
+ // ⌨️ mock: "⌘ K" (field) · "⌘K" (sm). The gap is its own span so a compact app bar can drop it (0.1.15)
112
+ const keyCap = <>{apple ? '⌘' : 'Ctrl'}{size === 'sm' ? null : <span data-ab-part="key-gap"> </span>}K</>;
104
113
  // 🧩 inner content
105
- const inner = (
114
+ const inner = home ? (
115
+ <>
116
+ <AbIcon name="search" size={size === 'sm' ? 17 : 18} className={styles.abSearchTriggerIcon} />
117
+ <span className={styles.abSearchTriggerLabel} data-ab-part="search-label">{label}</span>
118
+ {compactLabel != null && <span className={clsx(styles.abSearchTriggerLabel, styles.abSearchTriggerShort)} data-ab-part="search-label-compact">{compactLabel}</span> /* 📱 0.1.15 */}
119
+ {/* 🚧 coming soon: tooltip + announced, never painted inside the field (spec §4) */}
120
+ {comingSoon ? <span className={styles.abSearchTriggerSrOnly}>, {comingSoonLabel}</span> : listen && <AbKbd className={styles.abSearchTriggerCap}>{keyCap}</AbKbd>}
121
+ </>
122
+ ) : (
106
123
  <>
107
124
  <AbIcon name="search" size={20} className={styles.abSearchTriggerIcon} />
108
125
  <span className={clsx(styles.abSearchTriggerLabel, compact && styles.abSearchTriggerSrOnly)}>{label}</span>
@@ -117,6 +134,9 @@ const AbSearchTrigger = ({ label = 'Search', onOpen, href, hotkey, shortcut, com
117
134
  'data-ab-part': 'search-trigger', // 🧩
118
135
  'aria-keyshortcuts': listen ? 'Meta+K Control+K' : undefined, // ♿ only announced when bound (James #3)
119
136
  'data-compact': compact ? 'true' : undefined, // 📱
137
+ 'data-variant': variant === 'field' ? 'field' : undefined, // 🔎 P6
138
+ 'data-size': size === 'sm' ? 'sm' : undefined, // 📱 P6
139
+ title: home && comingSoon ? comingSoonLabel : undefined, // 💬 P6: "coming soon" lives in the tooltip
120
140
  };
121
141
 
122
142
  // 🚧 coming soon: focusable, announced, inert
@@ -56,7 +56,7 @@
56
56
  box-sizing: border-box; /* 📦 */
57
57
  }
58
58
  .abSearchTrigger:focus-visible {
59
- outline: var(--ab-focus-ring-width, 2px) solid var(--ab-color-primary, #8f4c38); /* ♿ */
59
+ outline: var(--ab-focus-ring-width, 2px) solid var(--ab-color-accent, var(--ab-color-primary, #8f4c38)); /* ♿ */
60
60
  outline-offset: var(--ab-focus-ring-offset, 2px); /* ♿ */
61
61
  }
62
62
  .abSearchTrigger[aria-disabled='true'] { cursor: default; opacity: 0.72; } /* 🚧 */
@@ -68,3 +68,32 @@
68
68
  .abSearchTrigger[data-compact='true'] { flex: none; width: 40px; min-width: 40px; padding: 0; justify-content: center; } /* 🔘 */
69
69
  /* 🕶️ visually hidden, still read by screen readers */
70
70
  .abSearchTriggerSrOnly { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; flex: none; }
71
+
72
+ /* ===== 🏠 0.1.14 (P6, Home spec §4): variant="field" (300×36) · size="sm" (mobile 34px pill) ===== */
73
+ .abSearchTrigger[data-variant='field'] {
74
+ width: var(--ab-search-trigger-width, 300px); max-width: 100%; height: 36px; /* 📏 desktop 360 / tablet 260 via the var */
75
+ gap: 8px; padding: 0 6px 0 10px; /* 📦 */
76
+ border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); border-radius: var(--ab-radius-button, 10px); /* 🔲 */
77
+ background: var(--ab-color-card, #fff); color: var(--ab-color-faint, #807062); /* 🎨 */
78
+ font-size: 13.5px; line-height: 1; box-shadow: var(--ab-shadow-card, 0 1px 2px rgb(33 26 22 / 0.05)); /* 🔤 🌗 */
79
+ }
80
+ .abSearchTrigger[data-size='sm'] {
81
+ flex: none; width: auto; max-width: none; height: 34px; /* 📏 */
82
+ gap: 6px; padding: 0 6px 0 10px; /* 📦 */
83
+ border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); border-radius: var(--ab-radius-pill, 999px); /* 💊 */
84
+ background: var(--ab-color-card, #fff); color: var(--ab-color-faint, #807062); font-size: 13px; line-height: 1; /* 🎨 🔤 */
85
+ }
86
+ .abSearchTrigger[data-variant='field']:hover, .abSearchTrigger[data-size='sm']:hover { border-color: color-mix(in srgb, var(--ab-color-accent, #a67c52) 40%, transparent); } /* 🖱️ */
87
+ .abSearchTrigger[data-variant='field']:focus-visible, .abSearchTrigger[data-size='sm']:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; } /* ♿ */
88
+ /* ⌨️ the single key cap (mock `kbd`): 20px, radius 5, 2px bottom border, 11/600 --muted */
89
+ .abSearchTriggerCap.abSearchTriggerCap {
90
+ flex: none; display: inline-flex; align-items: center; justify-content: center; box-sizing: border-box; /* 📐 */
91
+ min-width: 20px; height: 20px; padding: 0 5px; margin-left: 2px; /* 📏 */
92
+ border: 1px solid var(--ab-color-border, rgb(92 64 48 / 0.13)); border-bottom-width: 2px; border-radius: var(--ab-radius-kbd, 5px); /* 🔲 */
93
+ background: var(--ab-color-kbd, #fff); color: var(--ab-color-muted, #6b5b50); font: 600 11px/1 var(--ab-font-body, inherit); /* 🔤 Inter: fine for ⌘ (spec §2) */
94
+ }
95
+ .abSearchTrigger[data-size='sm'] .abSearchTriggerCap { min-width: 18px; height: 18px; font-size: 10px; } /* 📱 */
96
+ .abSearchTrigger[data-variant='field'][aria-disabled='true'], .abSearchTrigger[data-size='sm'][aria-disabled='true'] { opacity: 1; } /* 🚧 the Home field looks the same while search is coming soon (the tooltip says so) */
97
+
98
+ /* 📱 0.1.15: the short label is hidden unless a compact AbAppBar (< 768px) swaps it in */
99
+ .abSearchTriggerShort { display: none; }