ab-nextjs-components 0.1.11 โ†’ 0.1.13

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 (122) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +30 -0
  3. package/ab-app-bar/index.tsx +181 -0
  4. package/ab-app-bar/styles.module.css +119 -0
  5. package/ab-avatar/index.tsx +2 -1
  6. package/ab-avatar/styles.module.css +32 -0
  7. package/ab-balloon/index.tsx +134 -23
  8. package/ab-balloon/styles.module.css +84 -7
  9. package/ab-brand/index.tsx +1 -1
  10. package/ab-button/helpers.ts +3 -1
  11. package/ab-button/index.tsx +17 -3
  12. package/ab-button/styles.module.css +42 -0
  13. package/ab-card/index.tsx +89 -0
  14. package/ab-card/styles.module.css +68 -0
  15. package/ab-collapsible/index.tsx +1 -1
  16. package/ab-color/index.tsx +1 -0
  17. package/ab-color/styles.module.css +32 -0
  18. package/ab-demo-box/index.tsx +1 -0
  19. package/ab-demo-box/styles.module.css +32 -0
  20. package/ab-demo-code/index.tsx +1 -0
  21. package/ab-demo-code/styles.module.css +32 -0
  22. package/ab-icon/builtin.ts +15 -1
  23. package/ab-icon/helpers.ts +37 -0
  24. package/ab-icon/index.tsx +14 -8
  25. package/ab-icon/registrar.tsx +68 -0
  26. package/ab-icon-button/index.tsx +8 -3
  27. package/ab-image/index.tsx +1 -0
  28. package/ab-image/styles.module.css +32 -0
  29. package/ab-info/index.tsx +2 -1
  30. package/ab-info/styles.module.css +32 -0
  31. package/ab-input/index.tsx +1 -0
  32. package/ab-input/styles.module.css +1 -0
  33. package/ab-install-snippet/styles.module.css +32 -8
  34. package/ab-kbd/index.tsx +65 -0
  35. package/ab-kbd/styles.module.css +55 -0
  36. package/ab-key-feature/index.tsx +2 -1
  37. package/ab-key-feature/styles.module.css +32 -0
  38. package/ab-like-button/index.tsx +1 -1
  39. package/ab-link/index.tsx +112 -0
  40. package/ab-link/locale.ts +53 -0
  41. package/ab-locale-switcher/index.tsx +17 -0
  42. package/ab-locale-switcher/styles.module.css +11 -0
  43. package/ab-main-headline/index.tsx +1 -0
  44. package/ab-main-headline/styles.module.css +32 -0
  45. package/ab-menu/index.tsx +6 -5
  46. package/ab-menu/styles.module.css +32 -0
  47. package/ab-name/index.tsx +1 -0
  48. package/ab-name/styles.module.css +32 -0
  49. package/ab-navbar/index.tsx +54 -46
  50. package/ab-navbar/styles.module.css +84 -28
  51. package/ab-navbar/view.tsx +163 -0
  52. package/ab-package-card/index.tsx +94 -0
  53. package/ab-package-card/styles.module.css +41 -0
  54. package/ab-page-paginator/index.tsx +1 -0
  55. package/ab-page-paginator/styles.module.css +32 -0
  56. package/ab-page-switcher/index.tsx +1 -0
  57. package/ab-page-switcher/styles.module.css +32 -0
  58. package/ab-preview/index.tsx +1 -0
  59. package/ab-preview/styles.module.css +32 -0
  60. package/ab-price/index.tsx +1 -0
  61. package/ab-price/styles.module.css +32 -0
  62. package/ab-price-tag/index.tsx +1 -0
  63. package/ab-price-tag/styles.module.css +32 -0
  64. package/ab-product/index.tsx +1 -0
  65. package/ab-product/styles.module.css +32 -0
  66. package/ab-product-item/index.tsx +1 -0
  67. package/ab-product-item/styles.module.css +32 -0
  68. package/ab-search-result/index.tsx +1 -0
  69. package/ab-search-result/styles.module.css +32 -0
  70. package/ab-search-trigger/index.tsx +142 -0
  71. package/ab-search-trigger/styles.module.css +70 -0
  72. package/ab-sidebar/index.tsx +88 -49
  73. package/ab-sidebar/styles.module.css +136 -31
  74. package/ab-sidebar/view.tsx +182 -0
  75. package/ab-switch-back/index.tsx +2 -1
  76. package/ab-switch-back/styles.module.css +32 -0
  77. package/ab-tab/index.tsx +2 -1
  78. package/ab-tab/styles.module.css +32 -0
  79. package/ab-tabs/index.tsx +1 -0
  80. package/ab-tabs/styles.module.css +32 -0
  81. package/ab-test-hello/index.tsx +1 -0
  82. package/ab-test-hello/styles.module.css +32 -0
  83. package/ab-text/index.tsx +1 -0
  84. package/ab-text/styles.module.css +32 -0
  85. package/ab-toc/index.tsx +124 -0
  86. package/ab-toc/styles.module.css +54 -0
  87. package/css/chrome-mq.css +32 -0
  88. package/css/doodle.css +32 -0
  89. package/css/logo.css +32 -0
  90. package/css/spinner.css +32 -0
  91. package/css/toast.css +32 -0
  92. package/index.ts +18 -0
  93. package/package.json +27 -10
  94. package/server/ab-avatar/index.tsx +2 -1
  95. package/server/ab-avatar/styles.module.css +32 -0
  96. package/server/ab-badge/index.tsx +1 -0
  97. package/server/ab-badge/styles.module.css +32 -0
  98. package/server/ab-brand/index.tsx +1 -1
  99. package/server/ab-button/index.tsx +1 -1
  100. package/server/ab-button/styles.module.css +11 -0
  101. package/server/ab-icon/index.tsx +13 -8
  102. package/server/ab-key-feature/index.tsx +2 -1
  103. package/server/ab-key-feature/styles.module.css +32 -0
  104. package/server/ab-name/index.tsx +1 -0
  105. package/server/ab-name/styles.module.css +32 -0
  106. package/server/ab-nav-link/index.tsx +2 -1
  107. package/server/ab-nav-link/styles.module.css +32 -0
  108. package/server/ab-navbar/index.tsx +44 -45
  109. package/server/ab-polygon/index.tsx +1 -0
  110. package/server/ab-polygon/styles.module.css +32 -0
  111. package/server/ab-sidebar/index.tsx +44 -49
  112. package/server/ab-switch-back/index.tsx +2 -1
  113. package/server/ab-switch-back/styles.module.css +32 -0
  114. package/server/ab-test-hello/index.tsx +1 -0
  115. package/server/ab-test-hello/styles.module.css +32 -0
  116. package/server/ab-text/index.tsx +1 -0
  117. package/server/ab-text/styles.module.css +32 -0
  118. package/server/index.ts +1 -0
  119. package/styles.css +32 -0
  120. package/types/index.d.ts +35 -0
  121. package/server/ab-navbar/styles.module.css +0 -35
  122. package/server/ab-sidebar/styles.module.css +0 -41
package/CHANGELOG.md CHANGED
@@ -1,3 +1,39 @@
1
+ ## 0.1.13 โ€” 2026-10-16
2
+
3
+ * ๐Ÿ”— **`AbLinkProvider` (new, `ab-nextjs-components/ab-link`)**: every component link now renders through `AbLink`, so an app can inject a locale-aware `Link` once. `useAbLink`, `AbLink`, `AbLinkComponent` and `AbLinkProps` are exported. It's the only `next/link` import (test-guarded)
4
+ * ๐Ÿ”ฃ **AbIcon (G2): SVG first, non-breaking fallback.** Registered / explicit / built-in names render AbIcons SVGs. An unregistered name still renders the Material Symbols ligature (`data-ab-icon-fallback="font"`, as before) and warns once in development, so nothing goes blank in a patch; register every name before the app drops the font. **`AbIconRegistrar`** (`ab-nextjs-components/ab-icon/registrar`) is the server-safe way to register icons from a Server Component layout. 7 more built-ins: `chevron_left`, `chevron_right`, `menu`, `more_vert`, `search`, `close`, `expand_more`. AbMenu icons are AbIcons now (filled when selected)
5
+ * ๐Ÿงญ **AbSidebar v2 (G40)**: sections, `activeHref`, filled active icon, `aria-current`, badges, one child level, a 72px rail with balloon tooltips, and a collapse button (`aria-expanded`, `aria-controls`, hidden without JS). Client and server twins share `ab-sidebar/view`. Legacy `links` / `page` / `brandLabel` still work
6
+ * ๐Ÿ“ฑ **AbNavbar v2 (G41)**: link and button items, filled active icon, `aria-current`, safe-area padding. The server twin takes link items only
7
+ * ๐Ÿงฑ **AbAppBar (new, G43)**: brand, search, nav, actions, sticky with a hairline, and a "More" overflow `AbMenu` below 1180px (Escape and outside click close it, focus goes back to the trigger). The nav stays inline without JS
8
+ * ๐Ÿ”Ž **AbSearchTrigger + AbKbd (new, G44)**: an `href` always renders a real `<a>` (works without JS, D24a: `/docs`); with `onOpen` too, JS intercepts plain clicks and opens the dialog. The โŒ˜K / Ctrl K hint and `aria-keyshortcuts` appear only while a hotkey is listening. `shortcut` (alias of `hotkey`), `compact` (icon-only, label for screen readers), `comingSoon` with `aria-disabled`. The hotkey is a local listener because `useAbHotkey` (G48) is not in hooks 0.1.7
9
+ * ๐Ÿƒ **AbCard + AbPackageCard (new, G45)**: one link per card, `ab-motion-interactive` timing, a 2px hover lift on laptop and up with a real pointer, and no lift under reduced motion
10
+ * ๐Ÿ“‘ **AbToc (new, G46)**: plain `#id` anchors, `aria-current="location"`, and an optional `onNavigate` (for `scrollToAbSection`)
11
+ * ๐Ÿ“œ **Panes scrolling (D35/G55):** with core 0.1.6 the page never scrolls, the main pane does. `getAbMainScroller()` / `AB_MAIN_SCROLLER_SELECTOR` (`[data-ab-part="main-content"]`) from `ab-nextjs-components/ab-toc` give the `root` for `useAbScrollSpy` (call it in an effect or handler, never during render; `import { getAbMainScroller } from 'ab-nextjs-components/ab-toc'`, also on the root barrel with `AbToc`) and the `container` for `scrollToAbSection`; a plain `#id` jump scrolls the pane on its own. In panes the AbAppBar is the header row outside the scroller, so it stays put without the document scrolling
12
+ * ๐ŸŒ **AbAppBar active link (Joseph):** without `activeHref` it uses the pathname minus the AbLinkProvider `locales` (or its own `locales` prop), like AbSidebar / AbNavbar, so `/fr/docs` marks Docs
13
+ * ๐Ÿงฉ **AbPackageCard names wrap at hyphens (Joseph):** a `<wbr>` after each `-` (`toAbPackageNameParts`), so narrow cards show `ab-nextjs-` / `components` on two lines instead of an ellipsis; `overflow-wrap: anywhere` splits a part only when it alone is wider than the card. Checked in WebKit at 1280 (no clipping, no overflow)
14
+ * ๐Ÿ”‘ **AbSidebar item `id`:** optional, used as the React key (`id ?? href`) so two items may share an href
15
+ * ๐Ÿ†” **AbIcon per-instance ids (Joseph):** every render suffixes the SVG ids and `url(#โ€ฆ)` refs with `useId()` (`scopeAbIconIds`), so two filled Homes never share a mask and a hidden twin can't turn the active Home into a solid square
16
+ * ๐ŸŽˆ **AbBalloon a11y**: `role="tooltip"`, `aria-describedby` on the trigger, shows on focus, a 300ms hover delay (`AB_BALLOON_HOVER_DELAY`), Escape dismisses, `popIn` skipped under reduced motion. Without JS, CSS shows it on focus or hover. New `placement` and `delay` props
17
+ * ๐Ÿšซ **JS-off fallbacks**: AbInstallSnippet hides copy (the command shows the pnpm default). AbLocaleSwitcher with `getHref` renders a `<details>` list of `hreflang` links
18
+ * ๐Ÿ“ฑ **AbAppBar compact phone layout (< 768px):** tighter gaps, a shrinkable brand, an icon-only search pill and `compactActions` (shown instead of `actions`), so nothing overflows at 390px
19
+ * ๐Ÿ”˜ **AbButton** forwards any `aria-*` / `data-*` prop (e.g. `useAbAsideToggle().props`), and the `href` variant gets the theme's padding and colours (it rendered 20px tall with none). **AbIconButton** draws its glyph with AbIcon (filled while `active`, or `iconFilled`)
20
+ * ๐Ÿšง **AbNavbar** button items take `disabled` and `comingSoon` (inert, `aria-disabled`, a "Coming soon" tag)
21
+ * ๐ŸŒ **Locale-aware active state:** `AbLinkProvider` takes `locales`; AbSidebar / AbNavbar strip `/fr` from the pathname (or `activeHref` on the server twins, via a `locales` prop). `stripAbLocalePrefix` is exported. `AbLinkProvider` is generic over the link's props, so next-intl's `Link` needs no cast
22
+ * ๐Ÿƒ **AbCard / AbPackageCard** take `id`; AbPackageCard takes `media`, and names never wrap mid-name (ellipsis + `title`). **AbToc** takes `label` (alias of `title`). **AbSidebar** labels accept any node (`labelText` names the rail) and use M3 label-large
23
+ * ๐Ÿ’ป **AbInstallSnippet** puts the command on `--ab-color-code-surface` / `--ab-color-on-code-surface` with `--ab-font-code` (theme 0.3.4, with fallbacks)
24
+ * ๐Ÿ›ก๏ธ **Release age:** the expired `ab-nextjs-theme@0.3.3` exclude is gone, `.npmrc` no longer sets `minimumReleaseAge` (pnpm 11 ignores it there), and `minimumReleaseAgeStrict: true` is on. Tests guard all three; the per-entry expiry allowlist stays ready for scoped D33 exemptions
25
+ * ๐Ÿ“ Every code file carries the full house header with `@authors`; the npm author email is abrahamukachi@gmail.com
26
+ * ๐Ÿงช The release-age guard moved to `__tests__/release-age.test.ts`: excludes must be our own exact `ab-nextjs-*` versions and fail once expired
27
+ * โฌ†๏ธ Peers + dev: `ab-nextjs-theme ^0.3.4`, `ab-nextjs-icons ^0.2.4` (the filled `search` tab icon), `ab-nextjs-hooks ^0.1.7`
28
+ * โณ **D33:** exact `minimumReleaseAgeExclude` pins for the three siblings in the lockfile that are < 24h old: `ab-nextjs-icons@0.2.4`, `ab-nextjs-theme@0.3.4`, `ab-nextjs-hooks@0.1.7`, each until publish + 24h (2026-10-21 17:15 / 17:25 / 17:28 UTC). `release-age.test.ts` fails after that and rejects pins that aren't in the lockfile
29
+
30
+ ## 0.1.12 โ€” 2026-10-16
31
+
32
+ * โ™ฟ **AbInstallSnippet tabs pass AA in every state.** Each state now paints an explicit text/background pair from the live palette instead of a transparent tab and a 12% bronze tint: inactive `on-surface-variant` on `surface-container` (8.04:1 light / 9.67:1 dark), hover `on-surface` on an 8% `on-surface` state layer (12.63:1 / 10.39:1), active and active + hover `on-primary-container` on `primary-container` (13.28:1 / 7.22:1). Fallbacks are the light bronze palette, so it also passes without the theme
33
+ * ๐Ÿฅ‰ **New `AbButton type="filled"`** (client + server): solid bronze `--md-sys-color-primary` with `on-primary` label and icon. Sets `data-type="filled"`, styled with hover / focus / disabled by `ab-nextjs-theme@^0.3.3`; a `.isFilled` fallback paints the rest state on older themes. `AbButtonType` gains `'filled'`
34
+ * โฌ†๏ธ **`ab-nextjs-theme ^0.3.3`** (peer + dev, was `^0.3.1`) for the filled hover / focus / disabled states and the button icon-colour fix. The `.isFilled` fallback stays for apps still on an older theme
35
+ * Tests: contrast computed from the theme palette (light + dark, every state, plus the no-theme fallbacks); filled type on client + server twins. Checked in WebKit (ratios above; filled 6.47:1 light / 7.74:1 dark)
36
+
1
37
  ## 0.1.11 โ€” 2026-10-15
2
38
 
3
39
  * ๐Ÿ› **AbFlowDiagram: nodes no longer cover the header in small boxes.** At 390px wide the Live Playground's top node ("core") sat under the "Live Playground" header. With a header (title, live dot or caption) the root now gets `data-ab-header="true"`, and nodes + wires live in a stage that starts below the header band: `--ab-flow-diagram-inset-top` (default `2.75rem`, tunable). Node `x` / `y` stay 0โ€“100 but now map onto that stage, and the wires share the same box so they still meet the nodes. Without a header the stage is the full card (unchanged)
package/README.md CHANGED
@@ -66,6 +66,36 @@ Shipped assets: `assets/logos/ab-logo.svg`, `assets/spinners/3-dots-scale.svg`,
66
66
  * `<AbLogo>` defaults to the Ab logo **shipped in this package** (data URI / `ab-logo/ab-logo.svg`). Pass `src` to override.
67
67
 
68
68
 
69
+ ### Buttons & install snippet (0.1.12)
70
+
71
+ * `<AbButton type="filled">` ๐Ÿฅ‰ is a solid bronze button (`--md-sys-color-primary` background, `--md-sys-color-on-primary` label and icon). It sets `data-type="filled"`, which **`ab-nextjs-theme@^0.3.3`** styles with hover, focus and disabled states. On older themes a built-in fallback still paints the solid bronze rest state.
72
+ ```tsx
73
+ <AbButton type="filled" label="Get started" />
74
+ ```
75
+ * `<AbInstallSnippet>` tabs are **โ‰ฅ 4.5:1** (WCAG AA) in light and dark, active, inactive and hover: inactive = on-surface-variant on surface-container, hover = on-surface on an 8% state layer, active = on-primary-container on primary-container.
76
+
77
+ ### Docs shell (0.1.13) ๐Ÿงญ
78
+
79
+ New subpaths for the docs / PWA shell. All links go through **`AbLinkProvider`**, and every icon is an AbIcon (no Material Symbols font).
80
+
81
+ * **`ab-nextjs-components/ab-link`**: `<AbLinkProvider component={Link}>` swaps the link used by **every** Ab component (for example the locale-aware `Link` from `ab-nextjs-i18n`). `useAbLink()` and `<AbLink>` are exported too. It is the package's only `next/link` import (test-guarded).
82
+ ```tsx
83
+ <AbLinkProvider component={Link}>{children}</AbLinkProvider>
84
+ ```
85
+ * **`<AbSidebar>` v2 (G40)**: `sections=[{ id, label, items: [{ href, icon, label, badge?, items? }] }]`, `activeHref`, `collapsed` / `defaultCollapsed` / `onCollapsedChange`, `header`, `labels`. The active item gets `aria-current="page"` and a filled icon. Collapsed it becomes a 72px rail with balloon tooltips. The collapse button has `aria-expanded` + `aria-controls` and is hidden when JS is off. The server twin renders the same markup (no toggle). Legacy `links` / `page` still work.
86
+ * **`<AbNavbar>` v2 (G41)**: `items` of `{ kind: 'link', href, icon, label }` or `{ kind: 'button', id, icon, label, onSelect, expanded?, controls? }`, filled active icon, `aria-current`, safe-area padding.
87
+ * **`<AbAppBar>` (G43)**: `brand`, `search`, `nav=[{ href, label }]`, `activeHref`, `actions`, `leading`, sticky with the theme hairline. Below **1180px** the nav moves into a "More" `AbMenu` (G26). It closes on Escape and outside click. With JS off the nav stays inline.
88
+ * **`<AbSearchTrigger>` + `<AbKbd>` (G44)**: shows โŒ˜K on Apple and Ctrl K elsewhere, sets `aria-keyshortcuts="Meta+K Control+K"`, calls `onOpen` (button) or falls back to `href` (link). `comingSoon` makes it `aria-disabled`.
89
+ * **`<AbCard>` / `<AbPackageCard>` (G45)**: one link per card (the title, stretched over the card). Hover lifts 2px on laptop and up only, never under `prefers-reduced-motion`.
90
+ * **`<AbToc>` (G46)**: plain `#id` links, `aria-current="location"`. Pair with `useAbScrollSpy` / `scrollToAbSection` from `ab-nextjs-hooks@0.1.7`.
91
+ * **`<AbBalloon>`** is now a real tooltip: `role="tooltip"`, `aria-describedby` on the trigger, shows on focus, after 300ms on hover, and hides on Escape.
92
+ * **JS off**: `<AbInstallSnippet>` shows the pnpm command and hides copy. `<AbLocaleSwitcher getHref>` falls back to a `<details>` list of `hreflang` links.
93
+ * โš ๏ธ **AbIcon has no font fallback any more.** An unknown name renders an empty box and warns once in development. The client AbIcon only knows registered icons, so register the ones your sidebar / navbar use:
94
+ ```ts
95
+ import code from 'ab-nextjs-icons/ab-icons/icons/code'
96
+ registerAbIcons({ code })
97
+ ```
98
+
69
99
  ## Getting Started
70
100
 
71
101
  ### Installation
@@ -0,0 +1,181 @@
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: AbAppBar (G43)
28
+ * @file: ab-app-bar/index.tsx
29
+ * @type: Client Component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * <AbAppBar
34
+ * brand={<AbBrand />}
35
+ * search={<AbSearchTrigger onOpen={openSearch} />}
36
+ * nav={[{ href: '/docs', label: 'Docs' }, { href: '/components', label: 'Components' }]}
37
+ * activeHref="/docs"
38
+ * actions={<AbThemeToggle />}
39
+ * />
40
+ */
41
+
42
+ /*
43
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
44
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
45
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
46
+ */
47
+
48
+ 'use client';
49
+
50
+ // โš›๏ธ React
51
+ import { useEffect, useId, useRef, useState, type ReactElement, type ReactNode } from 'react';
52
+ // ๐Ÿงต classes
53
+ import clsx from 'clsx';
54
+ // ๐Ÿ”— G42 link
55
+ import Link, { stripAbLocalePrefix, useAbLocales } from '../ab-link';
56
+ // ๐Ÿงญ current route (fallback when `activeHref` is omitted, like AbSidebar / AbNavbar)
57
+ import { usePathname } from 'next/navigation';
58
+ // ๐Ÿ”ฃ icons (more_vert is a built-in)
59
+ import AbIcon from '../ab-icon';
60
+ // ๐Ÿ“‹ the overflow menu (G26)
61
+ import AbMenu from '../ab-menu';
62
+ // ๐ŸŽจ styles
63
+ import styles from './styles.module.css';
64
+
65
+ /** ๐Ÿ”— a top-level destination */
66
+ export interface AbAppBarNavItem {
67
+ href: string; // ๐Ÿ”—
68
+ label: string; // ๐Ÿท๏ธ
69
+ }
70
+
71
+ /** โš™๏ธ props */
72
+ export interface AbAppBarProps {
73
+ brand?: ReactNode; // ๐Ÿท๏ธ logo / wordmark (left)
74
+ search?: ReactNode; // ๐Ÿ”Ž e.g. <AbSearchTrigger />
75
+ nav?: AbAppBarNavItem[]; // ๐Ÿงญ inline from 1180px, in the "More" menu below
76
+ activeHref?: string; // ๐ŸŽฏ default: the pathname without its locale prefix
77
+ locales?: readonly string[]; // ๐ŸŒ 0.1.13 (Joseph): stripped from the pathname (default: AbLinkProvider's), so `/fr/docs` marks `/docs`
78
+ actions?: ReactNode; // ๐Ÿ”˜ right side (theme toggle, locale switcher, GitHubโ€ฆ)
79
+ compactActions?: ReactNode; // ๐Ÿ“ฑ 0.1.13 (Joseph #3): shown INSTEAD of `actions` below 768px (e.g. only the theme toggle); the rest can live in the More menu or the nav sheet
80
+ leading?: ReactNode; // โ˜ฐ optional slot before the brand (e.g. a rail toggle)
81
+ sticky?: boolean; // ๐Ÿ“Œ default true (hairline under it)
82
+ labels?: { nav?: string; more?: string }; // ๐ŸŒ
83
+ className?: string; // ๐Ÿท๏ธ
84
+ }
85
+
86
+ /** ๐ŸŽฏ exact match or parent prefix ("/" only matches itself) */
87
+ const isActive = (href: string, active?: string) => !!active && (href === active || (href !== '/' && active.startsWith(`${href.replace(/\/$/, '')}/`)));
88
+
89
+ /**
90
+ * ๐Ÿงฑ AbAppBar (G43): brand, search, nav, actions, sticky with a hairline. Below 1180px the nav moves into a
91
+ * "More" overflow menu built on AbMenu (G26). JS off: the More button is hidden and the nav scrolls inline.
92
+ */
93
+ const AbAppBar = ({ brand, search, nav = [], activeHref, locales, actions, compactActions, leading, sticky = true, labels, className }: AbAppBarProps): ReactElement => {
94
+ // ๐ŸŒ the active link comes from the AbLinkProvider locales, same rule as AbSidebar / AbNavbar
95
+ const appLocales = useAbLocales();
96
+ const pathname = stripAbLocalePrefix(usePathname() ?? '', locales ?? appLocales); // ๐Ÿงญ `/fr/docs` โ†’ `/docs`
97
+ const current = activeHref ?? pathname; // ๐ŸŽฏ explicit wins
98
+ // ๐Ÿ†” menu id
99
+ const menuId = `ab-app-bar-more-${useId().replace(/:/g, '')}`;
100
+ // ๐Ÿ“‹ menu state
101
+ const [open, setOpen] = useState(false);
102
+ const wrap = useRef<HTMLDivElement>(null);
103
+ const btn = useRef<HTMLButtonElement>(null);
104
+ // โŽ‹ Escape + outside click close it
105
+ useEffect(() => {
106
+ if (!open) return;
107
+ const onKey = (e: KeyboardEvent) => {
108
+ if (e.key === 'Escape') {
109
+ setOpen(false);
110
+ btn.current?.focus(); // โ™ฟ focus back on the trigger
111
+ }
112
+ };
113
+ const onDown = (e: PointerEvent) => {
114
+ if (!wrap.current?.contains(e.target as Node)) setOpen(false); // ๐Ÿ‘‹
115
+ };
116
+ document.addEventListener('keydown', onKey);
117
+ document.addEventListener('pointerdown', onDown);
118
+ return () => {
119
+ document.removeEventListener('keydown', onKey);
120
+ document.removeEventListener('pointerdown', onDown);
121
+ };
122
+ }, [open]);
123
+
124
+ return (
125
+ <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}>
126
+ {leading}
127
+ {brand && <div className={styles.abAppBarBrand}>{brand}</div>}
128
+ {search && <div className={styles.abAppBarSearch}>{search}</div>}
129
+ {nav.length > 0 && (
130
+ <nav className={styles.abAppBarNav} aria-label={labels?.nav ?? 'Main'}>
131
+ <ul>
132
+ {nav.map((n) => {
133
+ const on = isActive(n.href, current); // ๐ŸŽฏ
134
+ return (
135
+ <li key={n.href}>
136
+ <Link href={n.href} className={styles.abAppBarLink} data-active={on ? 'true' : 'false'} aria-current={on ? 'page' : undefined}>{n.label}</Link>
137
+ </li>
138
+ );
139
+ })}
140
+ </ul>
141
+ </nav>
142
+ )}
143
+ <div className={styles.abAppBarActions}>
144
+ {/* ๐Ÿ”˜ actions; ๐Ÿ“ฑ below 768px `compactActions` replaces them (both rendered, CSS picks: no hydration flip) */}
145
+ {compactActions != null ? (
146
+ <>
147
+ <div className={styles.abAppBarActionsWide}>{actions}</div>
148
+ <div className={styles.abAppBarActionsCompact}>{compactActions}</div>
149
+ </>
150
+ ) : actions}
151
+ {nav.length > 0 && (
152
+ <div ref={wrap} className={styles.abAppBarMore}>
153
+ <button
154
+ ref={btn}
155
+ type="button"
156
+ className={styles.abAppBarMoreButton} // ๐Ÿ™ˆ โ‰ฅ 1180px and JS off
157
+ aria-label={labels?.more ?? 'More'}
158
+ aria-haspopup="menu"
159
+ aria-expanded={open}
160
+ aria-controls={menuId}
161
+ onClick={() => setOpen((o) => !o)}
162
+ >
163
+ <AbIcon name="more_vert" size={24} />
164
+ </button>
165
+ <AbMenu
166
+ id={menuId}
167
+ hidden={!open}
168
+ isActive={open}
169
+ className={styles.abAppBarMenu}
170
+ items={nav.map((n) => ({ id: n.href, label: n.label, href: n.href, selected: isActive(n.href, current), onClick: () => setOpen(false) }))}
171
+ />
172
+ </div>
173
+ )}
174
+ </div>
175
+ </header>
176
+ );
177
+ };
178
+
179
+ // ๐Ÿ“ฆ exports
180
+ export default AbAppBar;
181
+ export { AbAppBar };
@@ -0,0 +1,119 @@
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: AbAppBar - Styles (G43)
28
+ * @file: ab-app-bar/styles.module.css
29
+ * @type: CSS Module
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
33
+ /*
34
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
36
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37
+ */
38
+
39
+ /* ๐Ÿงฑ bar */
40
+ .abAppBar {
41
+ width: 100%; /* โ†”๏ธ never wider than its container */
42
+ max-width: 100%; /* ๐Ÿšซ overflow */
43
+ min-width: 0; /* ๐Ÿšซ overflow (flex/grid child) */
44
+ display: flex; /* ๐Ÿ“ */
45
+ align-items: center; /* โ†•๏ธ */
46
+ gap: 16px; /* โ†”๏ธ */
47
+ min-height: var(--ab-app-bar-height, 64px); /* ๐Ÿ“ 0.1.13: 64px incl. the hairline (core 0.1.6 panes measure the header row, no offset to match) */
48
+ padding: 0 max(16px, env(safe-area-inset-right, 0px)) 0 max(16px, env(safe-area-inset-left, 0px)); /* ๐Ÿ“ฆ no block padding: 56px actions fit */
49
+ box-sizing: border-box; /* ๐Ÿ“ฆ */
50
+ background: var(--ab-color-surface, inherit); /* ๐ŸŽจ */
51
+ }
52
+ .abAppBar[data-sticky='true'] {
53
+ position: sticky; /* ๐Ÿ“Œ document layouts; in core 0.1.6 panes the bar is the header row OUTSIDE the main scroller, so it stays put on its own */
54
+ top: 0; /* โฌ†๏ธ */
55
+ z-index: 40; /* โฌ†๏ธ */
56
+ border-bottom: var(--ab-divider-hairline, 1px solid rgb(0 0 0 / 0.12)); /* โž– theme 0.3.4 hairline */
57
+ }
58
+ .abAppBarBrand { flex: none; display: flex; align-items: center; } /* ๐Ÿท๏ธ */
59
+ .abAppBarSearch { flex: 1 1 240px; min-width: 0; display: flex; } /* ๐Ÿ”Ž */
60
+ .abAppBarNav ul { display: flex; gap: 4px; list-style: none; margin: 0; padding: 0; } /* ๐Ÿงญ */
61
+ .abAppBarLink {
62
+ display: inline-flex; /* ๐Ÿ“ */
63
+ align-items: center; /* โ†•๏ธ */
64
+ height: 40px; /* ๐Ÿ“ */
65
+ padding: 0 12px; /* ๐Ÿ“ฆ */
66
+ border-radius: 999px; /* ๐ŸŸข */
67
+ color: inherit; /* ๐Ÿ–‹๏ธ */
68
+ text-decoration: none; /* ๐Ÿšซ */
69
+ font-weight: 500; /* ๐Ÿ”ค */
70
+ white-space: nowrap; /* โ†”๏ธ */
71
+ }
72
+ .abAppBarLink[data-active='true'] { background: var(--ab-color-secondary-container, rgb(0 0 0 / 0.08)); font-weight: 600; } /* ๐ŸŽฏ */
73
+ .abAppBarLink:focus-visible,
74
+ .abAppBarMoreButton:focus-visible {
75
+ outline: var(--ab-focus-ring-width, 2px) solid var(--ab-color-primary, #8f4c38); /* โ™ฟ */
76
+ outline-offset: var(--ab-focus-ring-offset, 2px); /* โ™ฟ */
77
+ }
78
+ .abAppBarActions { margin-inline-start: auto; display: flex; align-items: center; gap: 4px; flex: none; } /* ๐Ÿ”˜ */
79
+ .abAppBarActionsWide, .abAppBarActionsCompact { display: flex; align-items: center; gap: 4px; } /* ๐Ÿ”˜ */
80
+ .abAppBarActionsCompact { display: none; } /* ๐Ÿ™ˆ wide screens */
81
+ .abAppBarMore { position: relative; } /* ๐Ÿ“ */
82
+ .abAppBarMoreButton {
83
+ display: none; /* ๐Ÿ™ˆ wide screens */
84
+ place-items: center; /* ๐ŸŽฏ */
85
+ width: 40px; /* ๐Ÿ“ */
86
+ height: 40px; /* ๐Ÿ“ */
87
+ border: 0; /* ๐Ÿšซ */
88
+ border-radius: 999px; /* ๐ŸŸข */
89
+ background: transparent; /* ๐ŸŽจ */
90
+ color: inherit; /* ๐Ÿ–‹๏ธ */
91
+ cursor: pointer; /* ๐Ÿ‘† */
92
+ }
93
+ .abAppBarMenu { position: absolute; inset-inline-end: 0; top: calc(100% + 4px); min-width: 200px; max-width: calc(100vw - 16px); z-index: 50; } /* ๐Ÿ“‹ never wider than the screen */
94
+ .abAppBarMenu[hidden] { display: none; } /* ๐Ÿ™ˆ closed: no layout, no overflow (Joseph #3) */
95
+
96
+ /* ๐Ÿ“ฑ below 1180px: nav โ†’ "More" */
97
+ @media (max-width: 1179px) {
98
+ .abAppBarNav { display: none; } /* ๐Ÿ™ˆ */
99
+ .abAppBarMoreButton { display: inline-grid; } /* โ‹ฎ */
100
+ }
101
+ /* ๐Ÿšซ JS off: no menu, the nav stays inline and scrolls */
102
+ @media (max-width: 1179px) and (scripting: none) {
103
+ .abAppBarNav { display: block; overflow-x: auto; min-width: 0; } /* ๐Ÿงญ */
104
+ .abAppBarMore { display: none; } /* ๐Ÿ™ˆ */
105
+ }
106
+
107
+ /* ๐Ÿ“ฑ 0.1.13 (Joseph #3): compact phone layout (< 768px). Tighter gaps, the brand may shrink, the search
108
+ * pill becomes a 40px icon button (its label stays for screen readers), `compactActions` replace the
109
+ * actions. Result: no horizontal overflow at 390px. */
110
+ @media (max-width: 767px) {
111
+ .abAppBar { gap: 8px; padding-inline: max(12px, env(safe-area-inset-left, 0px)) max(8px, env(safe-area-inset-right, 0px)); } /* ๐Ÿ“ฆ */
112
+ .abAppBarBrand { flex: 0 1 auto; min-width: 0; overflow: hidden; } /* ๐Ÿท๏ธ may shrink */
113
+ .abAppBarSearch { flex: none; margin-inline-start: auto; } /* ๐Ÿ”Ž icon only, pushed right */
114
+ .abAppBarSearch > :global(.AbSearchTrigger) { width: 40px; min-width: 40px; padding: 0; justify-content: center; flex: none; } /* ๐Ÿ”˜ */
115
+ .abAppBarSearch > :global(.AbSearchTrigger) > :not(:global(.AbIcon)) { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; } /* ๐Ÿ•ถ๏ธ label + kbd */
116
+ .abAppBarActions { margin-inline-start: 0; gap: 0; } /* ๐Ÿ”˜ */
117
+ .abAppBar[data-has-compact-actions='true'] .abAppBarActionsWide { display: none; } /* ๐Ÿ™ˆ */
118
+ .abAppBar[data-has-compact-actions='true'] .abAppBarActionsCompact { display: flex; } /* ๐Ÿ‘€ */
119
+ }
@@ -8,13 +8,14 @@
8
8
  * @project: ab-nextjs-components
9
9
  * @name: AbAvatar - Client (port of lyd-avatar)
10
10
  * @file: ab-avatar/index.tsx
11
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
11
12
  */
12
13
 
13
14
  'use client';
14
15
 
15
16
  import type { ReactElement } from 'react';
16
17
  import Image from 'next/image';
17
- import Link from 'next/link';
18
+ import Link from '../ab-link'; // ๐Ÿ”— G42: injectable via AbLinkProvider (default next/link)
18
19
  import clsx from 'clsx';
19
20
  import styles from './styles.module.css';
20
21
 
@@ -1,3 +1,35 @@
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: styles.module.css
28
+ * @file: ab-avatar/styles.module.css
29
+ * @type: CSS Stylesheet
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
1
33
  /* AbAvatar โ€” plain CSS (no Tailwind apply) */
2
34
  .abAvatar {
3
35
  display: flex;
@@ -5,51 +5,162 @@
5
5
  * ~~~~~~~~~~~~
6
6
  * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
7
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
+ *
8
26
  * @project: ab-nextjs-components
9
- * @name: AbBalloon - Client (Adapt โ€” title= locked)
27
+ * @name: AbBalloon
10
28
  * @file: ab-balloon/index.tsx
29
+ * @type: Client Component
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * <AbBalloon title="Clear">
34
+ * <button aria-label="Clear">ร—</button>
35
+ * </AbBalloon>
36
+ */
37
+
38
+ /*
39
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40
+ * MOTTO: We'll always do more ๐Ÿ˜œ!!!
41
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
11
42
  */
12
43
 
13
44
  'use client';
14
45
 
15
- import type { ReactElement, ReactNode } from 'react';
46
+ // โš›๏ธ React
47
+ import { cloneElement, isValidElement, useCallback, useEffect, useId, useRef, useState, type FocusEvent, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
48
+ // ๐Ÿงต classes
16
49
  import clsx from 'clsx';
50
+ // ๐ŸŽฌ the tooltip pops in with the package keyframes (reduced-motion safe in ab-nextjs-animations)
51
+ import 'ab-nextjs-animations/pop-in/styles.css';
52
+ // ๐ŸŽจ styles
17
53
  import styles from './styles.module.css';
18
54
 
55
+ /** โฑ๏ธ hover delay before the balloon shows (focus shows it at once). */
56
+ export const AB_BALLOON_HOVER_DELAY = 300;
57
+
58
+ // โš™๏ธ props
19
59
  export interface AbBalloonProps {
20
- /** Native tooltip text โ€” locked API (`title=`). */
60
+ /** ๐Ÿ’ฌ tooltip text (same prop name as before: `title=`). */
21
61
  title?: string;
22
- className?: string;
23
- hidden?: boolean;
24
- disabled?: boolean;
25
- children: ReactNode;
62
+ /** ๐Ÿงญ side of the trigger (default `top`). */
63
+ placement?: 'top' | 'bottom' | 'start' | 'end';
64
+ /** โฑ๏ธ hover delay in ms (default 300). */
65
+ delay?: number;
66
+ className?: string; // ๐Ÿท๏ธ
67
+ hidden?: boolean; // ๐Ÿ™ˆ render the child alone
68
+ disabled?: boolean; // ๐Ÿšซ no balloon
69
+ children: ReactNode; // ๐ŸŽฏ the trigger (ideally ONE focusable element)
26
70
  }
27
71
 
28
72
  /**
29
- * AbBalloon โ€” Phase 2 Adapt.
30
- * Uses the native `title=` tooltip (locked). Not a port of the LYD hover balloon.
73
+ * ๐ŸŽˆ AbBalloon (0.1.13, accessible) โ€” a real tooltip instead of the native `title=`:
74
+ * - โ™ฟ `role="tooltip"` + `aria-describedby` on the trigger (added to a single element child)
75
+ * - โŒจ๏ธ shows on keyboard focus at once, hides on blur and Escape
76
+ * - ๐Ÿ–ฑ๏ธ shows after a 300ms hover delay, hides on leave
77
+ * - ๐ŸŽฌ `popIn` from ab-nextjs-animations (no motion under prefers-reduced-motion)
78
+ * - ๐Ÿšซ JS off: the balloon shows on `:focus-within` / `:hover` with CSS alone
31
79
  */
32
- const AbBalloon = ({
33
- title,
34
- className,
35
- hidden = false,
36
- disabled = false,
37
- children,
38
- }: AbBalloonProps): ReactElement => {
39
- if (hidden) {
40
- return <>{children}</>;
41
- }
80
+ const AbBalloon = ({ title, placement = 'top', delay = AB_BALLOON_HOVER_DELAY, className, hidden = false, disabled = false, children }: AbBalloonProps): ReactElement => {
81
+ // ๐Ÿ†” tooltip id for aria-describedby
82
+ const id = useId();
83
+ // ๐Ÿ‘๏ธ open state
84
+ const [open, setOpen] = useState(false);
85
+ // โฑ๏ธ hover timer
86
+ const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
87
+ // ๐Ÿงน clear the timer
88
+ const clear = useCallback(() => {
89
+ if (timer.current) clearTimeout(timer.current); // โน๏ธ
90
+ timer.current = null;
91
+ }, []);
92
+ // โ™ฟ reduced motion: no popIn (ab-nextjs-animations/pop-in has no reduced-motion rule)
93
+ const [still, setStill] = useState(false);
94
+ useEffect(() => {
95
+ const mq = window.matchMedia?.('(prefers-reduced-motion: reduce)'); // ๐Ÿ”
96
+ if (!mq) return;
97
+ const sync = () => setStill(mq.matches); // ๐Ÿ”„
98
+ sync();
99
+ mq.addEventListener?.('change', sync); // ๐Ÿ‘‚
100
+ return () => mq.removeEventListener?.('change', sync); // ๐Ÿงน
101
+ }, []);
102
+ // ๐Ÿงน unmount
103
+ useEffect(() => clear, [clear]);
104
+
105
+ // ๐Ÿ™ˆ nothing to show
106
+ if (hidden) return <>{children}</>;
107
+ const active = !disabled && !!title; // โœ…
108
+
109
+ // ๐Ÿ–ฑ๏ธ hover in: wait `delay` ms
110
+ const onPointerEnter = () => {
111
+ if (!active) return;
112
+ clear();
113
+ timer.current = setTimeout(() => setOpen(true), delay); // โฑ๏ธ
114
+ };
115
+ // ๐Ÿ–ฑ๏ธ hover out
116
+ const onPointerLeave = () => {
117
+ clear();
118
+ setOpen(false); // ๐Ÿ‘‹
119
+ };
120
+ // โŒจ๏ธ focus in: show now
121
+ const onFocus = () => {
122
+ if (active) setOpen(true);
123
+ };
124
+ // โŒจ๏ธ focus left the whole balloon
125
+ const onBlur = (e: FocusEvent<HTMLSpanElement>) => {
126
+ if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setOpen(false);
127
+ };
128
+ // โŽ‹ Escape dismisses (WCAG 1.4.13)
129
+ const onKeyDown = (e: KeyboardEvent<HTMLSpanElement>) => {
130
+ if (e.key === 'Escape' && open) {
131
+ clear();
132
+ setOpen(false);
133
+ }
134
+ };
135
+
136
+ // ๐Ÿ”— describe the trigger: a single element child gets aria-describedby
137
+ const trigger = active && isValidElement<{ 'aria-describedby'?: string }>(children)
138
+ ? cloneElement(children, { 'aria-describedby': clsx(children.props['aria-describedby'], id) || undefined })
139
+ : children;
42
140
 
43
141
  return (
44
142
  <span
45
- className={clsx('AbBalloon', styles.abBalloon, className)}
46
- title={disabled ? undefined : title}
47
- data-disabled={disabled ? 'true' : 'false'}
143
+ className={clsx('AbBalloon', styles.abBalloon, className)} // ๐Ÿท๏ธ
144
+ data-disabled={disabled ? 'true' : 'false'} // ๐Ÿšซ
145
+ data-open={open ? 'true' : 'false'} // ๐Ÿ‘๏ธ
146
+ data-placement={placement} // ๐Ÿงญ
147
+ data-ab-part="balloon" // ๐Ÿงฉ
148
+ onPointerEnter={onPointerEnter}
149
+ onPointerLeave={onPointerLeave}
150
+ onFocus={onFocus}
151
+ onBlur={onBlur}
152
+ onKeyDown={onKeyDown}
48
153
  >
49
- {children}
154
+ {trigger}
155
+ {active && (
156
+ <span id={id} role="tooltip" className={clsx(styles.abBalloonTip, open && !still && 'popIn')} data-ab-part="balloon-tip">
157
+ {title}
158
+ </span>
159
+ )}
50
160
  </span>
51
161
  );
52
162
  };
53
163
 
164
+ // ๐Ÿ“ฆ exports
54
165
  export default AbBalloon;
55
166
  export { AbBalloon };