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.
- package/CHANGELOG.md +36 -0
- package/README.md +30 -0
- package/ab-app-bar/index.tsx +181 -0
- package/ab-app-bar/styles.module.css +119 -0
- package/ab-avatar/index.tsx +2 -1
- package/ab-avatar/styles.module.css +32 -0
- package/ab-balloon/index.tsx +134 -23
- package/ab-balloon/styles.module.css +84 -7
- package/ab-brand/index.tsx +1 -1
- package/ab-button/helpers.ts +3 -1
- package/ab-button/index.tsx +17 -3
- package/ab-button/styles.module.css +42 -0
- package/ab-card/index.tsx +89 -0
- package/ab-card/styles.module.css +68 -0
- package/ab-collapsible/index.tsx +1 -1
- package/ab-color/index.tsx +1 -0
- package/ab-color/styles.module.css +32 -0
- package/ab-demo-box/index.tsx +1 -0
- package/ab-demo-box/styles.module.css +32 -0
- package/ab-demo-code/index.tsx +1 -0
- package/ab-demo-code/styles.module.css +32 -0
- package/ab-icon/builtin.ts +15 -1
- package/ab-icon/helpers.ts +37 -0
- package/ab-icon/index.tsx +14 -8
- package/ab-icon/registrar.tsx +68 -0
- package/ab-icon-button/index.tsx +8 -3
- package/ab-image/index.tsx +1 -0
- package/ab-image/styles.module.css +32 -0
- package/ab-info/index.tsx +2 -1
- package/ab-info/styles.module.css +32 -0
- package/ab-input/index.tsx +1 -0
- package/ab-input/styles.module.css +1 -0
- package/ab-install-snippet/styles.module.css +32 -8
- package/ab-kbd/index.tsx +65 -0
- package/ab-kbd/styles.module.css +55 -0
- package/ab-key-feature/index.tsx +2 -1
- package/ab-key-feature/styles.module.css +32 -0
- package/ab-like-button/index.tsx +1 -1
- package/ab-link/index.tsx +112 -0
- package/ab-link/locale.ts +53 -0
- package/ab-locale-switcher/index.tsx +17 -0
- package/ab-locale-switcher/styles.module.css +11 -0
- package/ab-main-headline/index.tsx +1 -0
- package/ab-main-headline/styles.module.css +32 -0
- package/ab-menu/index.tsx +6 -5
- package/ab-menu/styles.module.css +32 -0
- package/ab-name/index.tsx +1 -0
- package/ab-name/styles.module.css +32 -0
- package/ab-navbar/index.tsx +54 -46
- package/ab-navbar/styles.module.css +84 -28
- package/ab-navbar/view.tsx +163 -0
- package/ab-package-card/index.tsx +94 -0
- package/ab-package-card/styles.module.css +41 -0
- package/ab-page-paginator/index.tsx +1 -0
- package/ab-page-paginator/styles.module.css +32 -0
- package/ab-page-switcher/index.tsx +1 -0
- package/ab-page-switcher/styles.module.css +32 -0
- package/ab-preview/index.tsx +1 -0
- package/ab-preview/styles.module.css +32 -0
- package/ab-price/index.tsx +1 -0
- package/ab-price/styles.module.css +32 -0
- package/ab-price-tag/index.tsx +1 -0
- package/ab-price-tag/styles.module.css +32 -0
- package/ab-product/index.tsx +1 -0
- package/ab-product/styles.module.css +32 -0
- package/ab-product-item/index.tsx +1 -0
- package/ab-product-item/styles.module.css +32 -0
- package/ab-search-result/index.tsx +1 -0
- package/ab-search-result/styles.module.css +32 -0
- package/ab-search-trigger/index.tsx +142 -0
- package/ab-search-trigger/styles.module.css +70 -0
- package/ab-sidebar/index.tsx +88 -49
- package/ab-sidebar/styles.module.css +136 -31
- package/ab-sidebar/view.tsx +182 -0
- package/ab-switch-back/index.tsx +2 -1
- package/ab-switch-back/styles.module.css +32 -0
- package/ab-tab/index.tsx +2 -1
- package/ab-tab/styles.module.css +32 -0
- package/ab-tabs/index.tsx +1 -0
- package/ab-tabs/styles.module.css +32 -0
- package/ab-test-hello/index.tsx +1 -0
- package/ab-test-hello/styles.module.css +32 -0
- package/ab-text/index.tsx +1 -0
- package/ab-text/styles.module.css +32 -0
- package/ab-toc/index.tsx +124 -0
- package/ab-toc/styles.module.css +54 -0
- package/css/chrome-mq.css +32 -0
- package/css/doodle.css +32 -0
- package/css/logo.css +32 -0
- package/css/spinner.css +32 -0
- package/css/toast.css +32 -0
- package/index.ts +18 -0
- package/package.json +27 -10
- package/server/ab-avatar/index.tsx +2 -1
- package/server/ab-avatar/styles.module.css +32 -0
- package/server/ab-badge/index.tsx +1 -0
- package/server/ab-badge/styles.module.css +32 -0
- package/server/ab-brand/index.tsx +1 -1
- package/server/ab-button/index.tsx +1 -1
- package/server/ab-button/styles.module.css +11 -0
- package/server/ab-icon/index.tsx +13 -8
- package/server/ab-key-feature/index.tsx +2 -1
- package/server/ab-key-feature/styles.module.css +32 -0
- package/server/ab-name/index.tsx +1 -0
- package/server/ab-name/styles.module.css +32 -0
- package/server/ab-nav-link/index.tsx +2 -1
- package/server/ab-nav-link/styles.module.css +32 -0
- package/server/ab-navbar/index.tsx +44 -45
- package/server/ab-polygon/index.tsx +1 -0
- package/server/ab-polygon/styles.module.css +32 -0
- package/server/ab-sidebar/index.tsx +44 -49
- package/server/ab-switch-back/index.tsx +2 -1
- package/server/ab-switch-back/styles.module.css +32 -0
- package/server/ab-test-hello/index.tsx +1 -0
- package/server/ab-test-hello/styles.module.css +32 -0
- package/server/ab-text/index.tsx +1 -0
- package/server/ab-text/styles.module.css +32 -0
- package/server/index.ts +1 -0
- package/styles.css +32 -0
- package/types/index.d.ts +35 -0
- package/server/ab-navbar/styles.module.css +0 -35
- 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
|
+
}
|
package/ab-avatar/index.tsx
CHANGED
|
@@ -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;
|
package/ab-balloon/index.tsx
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
/**
|
|
60
|
+
/** ๐ฌ tooltip text (same prop name as before: `title=`). */
|
|
21
61
|
title?: string;
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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 โ
|
|
30
|
-
*
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
47
|
-
data-
|
|
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
|
-
{
|
|
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 };
|