ab-nextjs-components 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,15 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [0.7.1](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.7.0...v0.7.1) (2026-11-12)
6
+
7
+ * Normalize the changelog format and backfill missing entries.
8
+
9
+ ## [0.7.0](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.6.0...v0.7.0) (2026-11-06)
10
+
11
+ * 📋 **AbPropsTable (server component):** accessible, responsive docs prop tables from build-time structured data. Export it from the package root or `ab-nextjs-components/ab-props-table`; row/default/column/label types are exported too. An omitted default (or `{ kind: 'none' }`) means "No default", `{ kind: 'unknown' }` is explicitly unknown, and `{ kind: 'value', value }` renders a code value. All input is escaped text: no introspection, evaluation or raw HTML. Configurable captions/labels/column order, required/deprecated annotations, one keyboard-scrollable region, wrapping long types and light/dark token fallbacks are included.
12
+
1
13
  ## [0.6.0](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.5.0...v0.6.0) (2026-11-04)
2
14
 
3
15
  * ⚠️ **Breaking: `html` is now `trustedHtml`** on AbCodeBlock, AbDemoCode and AbPreviewCode. The string goes into `dangerouslySetInnerHTML` **without sanitizing**, so pass only HTML you render yourself (e.g. Shiki `codeToHtml`), never user input. Prefer `highlighted` / children. Rename the prop to upgrade.
@@ -40,7 +52,7 @@
40
52
  * ♿ **Code blocks:** the `pre` is focusable, so keyboard users can scroll it.
41
53
  * ⬆️ **Theme:** `ab-nextjs-theme` **^0.3.8**.
42
54
 
43
- ## [0.3.3](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.3.2...v0.3.3) (2026-11-03)
55
+ ## [0.3.3](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.3.2...v0.3.3) (2026-11-02)
44
56
 
45
57
  * 📌 **Icons pin dropped ([#20](https://github.com/abraham-ukachi/ab-nextjs-components/pull/20)):** the release-age pin for `ab-nextjs-icons` is removed.
46
58
  * 🎯 **AbSearchTrigger:** the small size is 46px.
@@ -62,6 +74,17 @@
62
74
 
63
75
  * 🔥 **Prune ([#17](https://github.com/abraham-ukachi/ab-nextjs-components/pull/17)):** 5 unused components are removed: `AbKeyFeature`, `AbMainHeadline`, `AbPreview`, `AbSwitchBack` and `AbTestHello` (and their server twins). ⚠️ Breaking if you imported them.
64
76
 
77
+ ## [0.2.3](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.2.2...v0.2.3) (2026-10-29)
78
+
79
+ * 🎪 **AbPlaygroundScene:** v6 scenes (welcome, all, `variant="auto"`), real export names in captions, a CSS locale cycle with stills, frame-card ratio, and the v6 card token
80
+ * 🔶 **AbButton:** owns per-type padding/size via `--ab-button-*` tokens; `size="lg"`, `color="bronze"` and opt-in `color="card"`; the server twin uses the client CSS (single source, twin guard)
81
+ * 🎠 **AbCarousel:** `autoHeight`, headless `AbCarouselProvider` with a region hook, `useAbCarouselKeys` (default scope `'main'`, `'document'` opt-in); each part resolves its own accent
82
+ * 📱 **AbMobileHeader:** extra row and 3-state theme, globe wiring, link fallback, compact mode, no-JS `<details>` language list, `barAt` to hide the bar from 768px
83
+ * 🧩 **AbThemeModeProvider** (`./ab-theme-mode`) so every theme toggle shares one mode; export map guarded
84
+ * 🔀 **AbFlowDiagram:** frame mode, rich nodes and dots
85
+ * 📥 **AbBottomDrawer:** close on swipe down and refocus its trigger
86
+ * ⬆️ `ab-nextjs-animations` `^0.2.5` and `ab-nextjs-theme` `^0.3.7` (with D33 pins at release time)
87
+
65
88
  ## [0.2.2](https://github.com/abraham-ukachi/ab-nextjs-components/compare/v0.2.1...v0.2.2) (2026-10-21)
66
89
 
67
90
  - 🌍 AbPackagePreviewComponents `labels` ({ button, chip, switch }); English defaults unchanged, the 0.2.1 `button` / `chip` props still work
@@ -150,7 +173,7 @@ Includes everything planned for 0.1.15, which is not released separately.
150
173
  * 📋 **`AbDrawerList` + `AbConfirmDrawer` presets (new, D38/D40).**
151
174
  * 🌍 **`presentation="menu" | "drawer" | "auto"` (G56)** on `AbLocaleSwitcher` and on the `AbAppBar` More menu. The drawer is an app-scope bottom sheet, and `auto` uses it below 768px. The default stays `menu`.
152
175
 
153
- ## 0.1.13 — 2026-10-16
176
+ ## [0.1.13](https://github.com/abraham-ukachi/ab-nextjs-components/compare/eba68a9f33aae456803645b145ed26a6a230ef92...v0.1.13) (2026-10-20)
154
177
 
155
178
  * 🔗 **`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)
156
179
  * 🔣 **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)
@@ -179,21 +202,21 @@ Includes everything planned for 0.1.15, which is not released separately.
179
202
  * ⬆️ 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`
180
203
  * ⏳ **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
181
204
 
182
- ## 0.1.12 — 2026-10-16
205
+ ## [0.1.12](https://github.com/abraham-ukachi/ab-nextjs-components/compare/5ba7d20bf57a602b68cd323c66ebe432424025b8...eba68a9f33aae456803645b145ed26a6a230ef92) (2026-10-16)
183
206
 
184
207
  * ♿ **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
185
208
  * 🥉 **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'`
186
209
  * ⬆️ **`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
187
210
  * 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)
188
211
 
189
- ## 0.1.11 — 2026-10-15
212
+ ## [0.1.11](https://github.com/abraham-ukachi/ab-nextjs-components/compare/f6fd1fa600e9c52d469bee9dfb5f042636d3aae3...5ba7d20bf57a602b68cd323c66ebe432424025b8) (2026-10-15)
190
213
 
191
214
  * 🐛 **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)
192
215
  * 📏 **AbFlowDiagram nodes scale with the card:** `container-type: inline-size` on the root; node text, padding, radius and the hub glow use clamped `cqi` sizes (13px on a 760px card, 11px at 390px)
193
216
  * 🪐 **AbFlowDiagram: side nodes are never clipped** (s04's `--ab-color-bronze` and s07's `reduced motion` were cut off at the card edge in a 390px box). The orbit now scales with the box. Each node is anchored at the same fraction of its own box as its position (`translate(-x%, -y%)` via `--ab-flow-node-x` / `-y`; `x = y = 50` is the old centring), so the outer ring pulls in by exactly the node's width, and the wire end stays inside the pill. Nodes + wires also sit inside a side margin, `--ab-flow-diagram-inset-x` (default `0.5rem`), and an over-long label ellipsises (`max-width: 100%`). Positions are clamped to 0–100 like the wires
194
217
  * Tests: header flag, stage insets shared by nodes + wires, 390px geometry, clamped scaling, proportional anchoring + side margin, s04 / s07 orbit geometry at 390 / 760px × 276 / 380px. Checked in WebKit at 390px: "core" top 9px → 53px (header ends at 33px); no node overlaps the header or is clipped at 390 / 760px. After the orbit fix: s04 + s07 have no node clipped (x or y) or over the header at 390 / 760px wide × 276px / 380px / default-ratio heights (before: 5 nodes clipped at 390px, 2 at 760px)
195
218
 
196
- ## 0.1.10 — 2026-10-14
219
+ ## [0.1.10](https://github.com/abraham-ukachi/ab-nextjs-components/compare/5e8d9e84398714e47ac947cc405009850eef2398...f6fd1fa600e9c52d469bee9dfb5f042636d3aae3) (2026-10-15)
197
220
 
198
221
  * **Motion comes from ab-nextjs-animations (>= 0.2.4, now a required peer):** no component CSS declares its own `transition`, `animation` or `@keyframes` any more. Each component imports the package stylesheet it needs:
199
222
  * AbCarousel: `slide-step` (direction-aware enter / leave via `data-ab-direction`) + `motion` (buttons, dots)
@@ -218,11 +241,11 @@ Includes everything planned for 0.1.15, which is not released separately.
218
241
  * **AbInstallSnippet (G35, new):** pnpm / npm / yarn / bun tabs (APG tablist), choice shared via `useAbLocalStorage`, copy button with polite status, `data-ab-swipe-ignore`; `getAbInstallCommand` helper
219
242
  * **AbLocaleSwitcher (G7, new):** menu button + `menuitemradio`, typeahead, `onSelect` or `getHref` (+ `hrefLang`)
220
243
  * **AbIcon (G2, new, `ab-nextjs-components/ab-icon`):** AbIcons as inline SVG; client twin resolves `svg` prop → `registerAbIcons` registry → Material Symbols font (never imports the full map); server twin renders any icon; weights 100–700 map to the icons package stroke table; 8 built-ins (arrows, theme, language, copy / check) imported per icon from `ab-nextjs-icons/ab-icons/icons/*` (needs icons >= 0.2.3)
221
- * **AbCarousel:** prev / next arrows now render through AbIcon (weight 300); `--ab-carousel-icon-stroke` removed (unreleased)
244
+ * **AbCarousel:** prev / next arrows now render through AbIcon (weight 300); `--ab-carousel-icon-stroke` removed
222
245
  * **AbFlowDiagram (G38, new, server component):** `figure role="img"` scenes, CSS-only draw + pulse, paused while inactive, 3 loops on mobile, reduced motion shows the poster frame; `getAbFlowEdgePath` helper
223
246
  * Dev: `happy-dom` + `@testing-library/react` for DOM tests
224
247
 
225
- ## 0.1.9 — 2026-10-14
248
+ ## [0.1.9](https://github.com/abraham-ukachi/ab-nextjs-components/compare/9d443f2ac9944d16951eb613f7a4bd1feab82712...5e8d9e84398714e47ac947cc405009850eef2398) (2026-10-14)
226
249
 
227
250
  - **AbLogo:** `wordmark` prop (`true` → "Elements", or any string) renders a mark + Quicksand Bold lockup (`font-quicksand-bold` from ab-nextjs-fonts); `color` prop (`--ab-logo-color`); light / dark (`html.dark`)
228
251
  - **AbLogo fix:** `naked` with no `src` now masks with the shipped Ab mark (via `--app-logo-url` fallback) instead of a bronze square when the chrome CSS isn't loaded
@@ -235,55 +258,50 @@ Includes everything planned for 0.1.15, which is not released separately.
235
258
  - **AbSplash:** StrictMode-safe teardown (`scheduleAbSplashFinish` / `cancelAbSplashFinish`); overflow failsafe verified in Chromium + WebKit
236
259
  - **Tooling:** `typecheck` script, `types/css.d.ts`, vitest automatic JSX, `scripts/build-demo.mjs`
237
260
 
238
- ## 0.1.8 — 2026-10-05
261
+ ## [0.1.8](https://github.com/abraham-ukachi/ab-nextjs-components/compare/bb3a452d8cd89d57d6a3951b2f640a58ecdeb775...9d443f2ac9944d16951eb613f7a4bd1feab82712) (2026-10-05)
239
262
 
240
263
  - **Chrome styles:** dialog, toast, logo (`span.app-logo`), spinner, and empty-state doodle CSS + SVG assets now ship here via `@import "ab-nextjs-components/styles.css"` (import after `ab-nextjs-theme/styles.css`)
241
264
  - **AbLogo:** comments corrected — mask fallback `--app-logo-url` is owned by this package’s chrome CSS, not the theme
242
265
 
243
- ## 0.1.7 — 2026-10-05
266
+ ## [0.1.7](https://github.com/abraham-ukachi/ab-nextjs-components/compare/e67e89dbeba6055e608d3fb1aa6aa2fb511ab6fc...bb3a452d8cd89d57d6a3951b2f640a58ecdeb775) (2026-10-05)
244
267
 
245
268
  - **AbNavbar:** root `<nav>` sets `data-ab-part="bottomBar"` (client + server)
246
269
 
247
- ## 0.1.6 — 2026-10-05
270
+ ## [0.1.6](https://github.com/abraham-ukachi/ab-nextjs-components/compare/1ede72f33ca1e6910c793454098ad9889a303bb2...e67e89dbeba6055e608d3fb1aa6aa2fb511ab6fc) (2026-10-05)
248
271
 
249
272
  - **AbSidebar:** renders `<nav data-ab-part="sidebar">` (was `<aside>`) so aside dialogs/menus never hit the sidebar
250
273
  - **AbMenu:** sets `data-id={id}` (keeps `id`) and `data-id` / `menu-item` on items so `useAbMenu` can open it; cancel is `li[role=close-menu]`
251
274
  - **AbLogo:** ships `ab-logo/ab-logo.svg` and defaults `src` to an inlined data URI of that asset; mask types without `src`/`mask` defer to `ab-nextjs-theme` `--app-logo-url`
252
275
 
253
- ## 0.1.5 — 2026-10-03
276
+ ## [0.1.5](https://github.com/abraham-ukachi/ab-nextjs-components/compare/fd3e776be781ea8ad0d7aa4d6ca56b31c0ae1a4a...1ede72f33ca1e6910c793454098ad9889a303bb2) (2026-10-03)
254
277
 
255
278
  - Publish to npm automatically from GitHub Actions with Trusted Publishing (OIDC + provenance, no NPM_TOKEN)
256
279
  - `next` peer is now `^16.3.4`; dev dependency on ab-nextjs-hooks comes from the registry
257
280
 
258
- ### Unreleased (chore/upgrade-next-16 — Skip-override / Phase 5 components)
259
-
260
- ## 0.1.4 — 2026-09-23
281
+ ## [0.1.4](https://github.com/abraham-ukachi/ab-nextjs-components/compare/8fcbcaa9e4d5dd35e63d6c9b84cb682f5f04d1c8...fd3e776be781ea8ad0d7aa4d6ca56b31c0ae1a4a) (2026-09-23)
261
282
 
262
283
  - Release from `main` after merge of PR #1 (Next 16.3.4 + Phase 1–5 ports).
263
284
 
264
-
265
285
  * **Port (client):** AbBrand, AbName, AbNavbar, AbSidebar, AbText, AbTestHello, AbKeyFeature, AbMainHeadline, AbPreview, AbProduct, AbProductItem, AbSwitchBack, AbDemoBox, AbDemoCode
266
286
  * **Port (server):** AbBrand, AbName, AbNavbar, AbSidebar, AbNavLink, AbText, AbTestHello, AbKeyFeature, AbSwitchBack
267
287
  * Select/MenuItem skipped — empty on Projects (GitHub-only historically)
268
288
  * Product/Preview adapted (Dexie/providers/i18n stripped); usable props API kept
269
- * Catalog **51 Done** (36 client / 15 server). Local only — no push.
270
-
271
- # Changelog
289
+ * Catalog **51 Done** (36 client / 15 server).
272
290
 
273
- ### Unreleased (chore/upgrade-next-16 — Phase 4 Port)
291
+ ### Phase 4 Port
274
292
 
275
293
  * **Port:** AbSearchbar, AbSearchResult, AbPagePaginator, AbPageSwitcher, AbProgressChips, AbPrice, AbPriceTag
276
294
  * **Adapt:** AbImage (Dexie / offline / background-removal stripped; next/image + optional fallback)
277
295
  * **Port (server):** AbPolygon
278
- * Catalog 28 Done (22 client / 6 server). Plain CSS modules. Local only — no push.
296
+ * Catalog 28 Done (22 client / 6 server). Plain CSS modules.
279
297
 
280
- ### Unreleased (chore/upgrade-next-16 — Phase 2 Adapt + Phase 3 Port)
298
+ ### Phase 2 Adapt + Phase 3 Port
281
299
 
282
300
  * **Adapt:** **AbBalloon** (`title=` locked) — Input now uses real AbBalloon
283
301
  * **Port:** AbAvatar (client + server), AbBadge (server), AbTab, AbTabs, AbMenu, AbCollapsible, AbColor, AbInfo, AbLikeButton
284
302
  * Plain CSS modules; LYD brand/nav/i18n stripped; Select/MenuItem skipped (not on Projects)
285
303
 
286
- ### Unreleased (chore/upgrade-next-16 — Phase 2)
304
+ ### Phase 2
287
305
 
288
306
  * Ported **AbIcon** (client + server) — Material Symbols ligatures
289
307
  * Ported **AbLogo** (client + server) — contained | outlined | hollow | naked; defaults from `ab-nextjs-icons` logos (`#a67c52`), optional `src` / `mask`
@@ -293,10 +311,22 @@ Includes everything planned for 0.1.15, which is not released separately.
293
311
  * Hard peers: next 16.3.4, react^19, clsx; soft optional peers: theme / icons / hooks / animations
294
312
  * Plain CSS modules (no `@apply`); theme `data-*` attrs preserved on buttons
295
313
 
296
- ### Unreleased (Phase 1)
314
+ ### Phase 1
297
315
 
298
316
  * Next.js **16.3.4** / React 19 tooling scaffold + Pending catalog
299
317
 
300
- ### 0.1.2
318
+ ## [0.1.3](https://github.com/abraham-ukachi/ab-nextjs-components/compare/9169fe98d2519db14aa68e2b00ebab83e5d88b59...8fcbcaa9e4d5dd35e63d6c9b84cb682f5f04d1c8) (2026-09-23)
319
+
320
+ * Staged Phase 5 publish ahead of the 0.1.4 release from main
321
+
322
+ ## [0.1.2](https://github.com/abraham-ukachi/ab-nextjs-components/compare/7131423436c545ae706725da0801decdb12ef055...9169fe98d2519db14aa68e2b00ebab83e5d88b59) (2024-06-01)
301
323
 
302
324
  * Stub package version bump
325
+
326
+ ## [0.1.1](https://github.com/abraham-ukachi/ab-nextjs-components/compare/6d7c433915135e537aebcf1fea69b2d932bef075...7131423436c545ae706725da0801decdb12ef055) (2024-06-01)
327
+
328
+ * Version bump to 0.1.1
329
+
330
+ ## 0.1.0 (2024-06-01)
331
+
332
+ * Initial release
@@ -0,0 +1,187 @@
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: AbPropsTable (unreleased docs props table)
28
+ * @file: ab-props-table/index.tsx
29
+ * @type: Server component (no hooks or browser APIs)
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage:
33
+ * 1+|> <AbPropsTable caption="AbButton props" rows={buildTimeRows} />
34
+ * 2+|> <AbPropsTable rows={[{ name: 'tone', type: "'soft' | 'solid'", default: { kind: 'value', value: "'soft'" } }]} />
35
+ */
36
+
37
+ /*
38
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
39
+ * MOTTO: We'll always do more 😜!!!
40
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
41
+ */
42
+
43
+ // ⚛️ React: plain elements only, so this entry stays safe in a React Server Component.
44
+ import { Fragment, type ReactElement } from 'react';
45
+ // 🧵 classes: let a docs page add layout without replacing the component's own classes.
46
+ import clsx from 'clsx';
47
+ // 🎨 styles: the table owns its width, wrapping, focus ring and scheme fallbacks.
48
+ import styles from './styles.module.css';
49
+
50
+ /** ⛔ No default was declared: visually a dash, with useful text for screen readers. */
51
+ export interface AbPropsTableDefaultNone {
52
+ kind: 'none';
53
+ }
54
+
55
+ /** ❓ Extraction could not establish a default: never confuse this with no default. */
56
+ export interface AbPropsTableDefaultUnknown {
57
+ kind: 'unknown';
58
+ }
59
+
60
+ /** ✅ A known default, already serialized as text by the build-time extraction step. */
61
+ export interface AbPropsTableDefaultValue {
62
+ kind: 'value';
63
+ value: string;
64
+ }
65
+
66
+ /** 🔀 All three extraction outcomes, with no runtime TypeScript inspection involved. */
67
+ export type AbPropsTableDefault = AbPropsTableDefaultNone | AbPropsTableDefaultUnknown | AbPropsTableDefaultValue;
68
+
69
+ /** 🔤 The four stable column ids; `columns` can reorder or omit any of them. */
70
+ export type AbPropsTableColumn = 'name' | 'type' | 'default' | 'description';
71
+
72
+ /** 🌍 Visible column headings and accessible status text can be localized at the call site. */
73
+ export interface AbPropsTableLabels {
74
+ name: string;
75
+ type: string;
76
+ default: string;
77
+ description: string;
78
+ required: string;
79
+ deprecated: string;
80
+ noDefault: string;
81
+ unknownDefault: string;
82
+ }
83
+
84
+ /** 🧾 One build-time-extracted prop. JSX/HTML-looking strings always remain ordinary text. */
85
+ export interface AbPropsTableRow {
86
+ name: string;
87
+ type: string;
88
+ default?: AbPropsTableDefault; // ⛔ omitted means "no default"; use kind: 'unknown' when that is not known.
89
+ description?: string;
90
+ required?: boolean;
91
+ deprecated?: boolean | string; // 🪦 true gives a generic notice; a string carries migration guidance.
92
+ }
93
+
94
+ /** ⚙️ Public component props. There is deliberately no raw HTML or runtime compiler input. */
95
+ export interface AbPropsTableProps {
96
+ rows: readonly AbPropsTableRow[]; // 🏗️ structured data generated during documentation builds.
97
+ caption?: string; // 🏷️ a visible table caption.
98
+ label?: string; // ♿ names both the scroll region and the caption when `caption` is absent.
99
+ labels?: Partial<AbPropsTableLabels>; // 🌍 partial overrides; English defaults fill the rest.
100
+ className?: string;
101
+ columns?: readonly AbPropsTableColumn[]; // 🧩 optional order/visibility; an empty array gets the default columns.
102
+ }
103
+
104
+ /** 🏷️ Stable English defaults, shared by every render (including SSR). */
105
+ export const AB_PROPS_TABLE_DEFAULT_LABELS: Readonly<AbPropsTableLabels> = {
106
+ name: 'Name',
107
+ type: 'Type',
108
+ default: 'Default',
109
+ description: 'Description',
110
+ required: 'Required',
111
+ deprecated: 'Deprecated',
112
+ noDefault: 'No default',
113
+ unknownDefault: 'unknown',
114
+ };
115
+
116
+ const AB_PROPS_TABLE_COLUMNS: readonly AbPropsTableColumn[] = ['name', 'type', 'default', 'description'];
117
+
118
+ /** 🪦 The required/deprecated details live with the prop name, not in an extra inaccessible column. */
119
+ function AbPropsTableNameCell({ row, labels }: { row: AbPropsTableRow; labels: AbPropsTableLabels }): ReactElement {
120
+ return (
121
+ <th scope="row" className={styles.abPropsTableName}>
122
+ <code translate="no">{row.name}</code>
123
+ {row.required && <span className={styles.abPropsTableRequired}>{labels.required}</span>}
124
+ {row.deprecated != null && row.deprecated !== false && (
125
+ <span className={styles.abPropsTableDeprecated} data-deprecated="true">
126
+ {labels.deprecated}{typeof row.deprecated === 'string' ? `: ${row.deprecated}` : ''}
127
+ </span>
128
+ )}
129
+ </th>
130
+ );
131
+ }
132
+
133
+ /** 🧱 Keep React, not a string template, responsible for escaping every value. */
134
+ const AbPropsTable = ({ rows, caption, label, labels: overrides, className, columns }: AbPropsTableProps): ReactElement => {
135
+ const labels = { ...AB_PROPS_TABLE_DEFAULT_LABELS, ...overrides }; // 🌍 only replace supplied labels.
136
+ const visibleColumns = columns?.length ? columns : AB_PROPS_TABLE_COLUMNS; // 🛟 an empty list cannot make a headerless table.
137
+ const accessibleLabel = label ?? caption ?? 'Component props'; // ♿ a useful region name even with no visible caption.
138
+ const visibleCaption = caption != null; // 👀 a custom caption is visible; fallback names remain visually hidden.
139
+
140
+ /** 📄 A cell renderer keeps column ordering in one place without eval or dynamic HTML. */
141
+ const renderCell = (column: AbPropsTableColumn, row: AbPropsTableRow): ReactElement | null => {
142
+ switch (column) {
143
+ case 'name':
144
+ return <AbPropsTableNameCell row={row} labels={labels} />;
145
+ case 'type':
146
+ return <td className={styles.abPropsTableCode}><code translate="no">{row.type}</code></td>;
147
+ case 'default': {
148
+ const value = row.default ?? { kind: 'none' as const }; // ⛔ absence is an explicit rendering decision.
149
+ if (value.kind === 'unknown') return <td className={styles.abPropsTableUnknown}>{labels.unknownDefault}</td>;
150
+ if (value.kind === 'value') return <td className={styles.abPropsTableCode}><code translate="no">{value.value}</code></td>;
151
+ return <td className={styles.abPropsTableNone}><span aria-hidden="true">—</span><span className={styles.srOnly}>{labels.noDefault}</span></td>;
152
+ }
153
+ case 'description':
154
+ return <td className={styles.abPropsTableDescription}>{row.description}</td>;
155
+ default:
156
+ return null; // 🛟 forward-compatible runtime guard; TypeScript limits calls to the four ids above.
157
+ }
158
+ };
159
+
160
+ return (
161
+ <div
162
+ className={clsx('AbPropsTable', 'ab-prose-none', styles.abPropsTable, className)}
163
+ data-ab-part="props-table"
164
+ role="region"
165
+ aria-label={accessibleLabel}
166
+ tabIndex={0} // ⌨️ the only tab stop: focused overflow regions respond to native arrow-key scrolling.
167
+ >
168
+ <table className={styles.abPropsTableGrid}>
169
+ <caption className={visibleCaption ? styles.abPropsTableCaption : styles.srOnly}>{caption ?? accessibleLabel}</caption>
170
+ <thead>
171
+ <tr>{visibleColumns.map((column) => <th key={column} scope="col" data-column={column}>{labels[column]}</th>)}</tr>
172
+ </thead>
173
+ <tbody>
174
+ {rows.map((row, index) => (
175
+ <tr key={`${row.name}-${index}`} data-required={row.required || undefined} data-deprecated={row.deprecated ? true : undefined}>
176
+ {visibleColumns.map((column) => <Fragment key={column}>{renderCell(column, row)}</Fragment>)}
177
+ </tr>
178
+ ))}
179
+ </tbody>
180
+ </table>
181
+ </div>
182
+ );
183
+ };
184
+
185
+ // 📦 Both import styles match the other package components.
186
+ export default AbPropsTable;
187
+ export { AbPropsTable };
@@ -0,0 +1,96 @@
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: AbPropsTable styles (unreleased)
28
+ * @file: ab-props-table/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
+ /* 📋 The border and surface follow the docs tokens. The local wrapper, never the page, scrolls. */
40
+ .abPropsTable {
41
+ --ab-props-table-surface: var(--ab-color-card, #fffdf9);
42
+ --ab-props-table-text: var(--ab-color-text, #211a16);
43
+ --ab-props-table-muted: var(--ab-color-muted, #6f635b);
44
+ --ab-props-table-border: var(--ab-color-border, rgb(92 64 48 / 0.18));
45
+ --ab-props-table-code: var(--ab-color-accent-text, #875d37);
46
+ max-inline-size: 100%; /* 📐 never widen the document or its prose parent. */
47
+ min-inline-size: 0;
48
+ margin: 0 0 1.25em; /* ↕️ docs prose rhythm, consistent with AbCodeBlock. */
49
+ overflow-x: auto; /* ↔️ narrow panes scroll here, so the keyboard has one useful stop. */
50
+ border: 1px solid var(--ab-props-table-border);
51
+ border-radius: var(--ab-radius-row, 8px);
52
+ background: var(--ab-props-table-surface);
53
+ color: var(--ab-props-table-text);
54
+ color-scheme: light dark; /* 🌗 native focus/scrollbar colors track the active scheme. */
55
+ font: 14px/1.55 var(--ab-font-body, system-ui, sans-serif);
56
+ }
57
+ .abPropsTable:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; } /* ♿ */
58
+ /* 🧱 A fixed layout shares space fairly; 640px is the local horizontal scroll threshold, not a page minimum. */
59
+ .abPropsTableGrid { inline-size: 100%; min-inline-size: 640px; border-collapse: collapse; table-layout: fixed; }
60
+ .abPropsTableCaption { padding: 12px 16px; border-block-end: 1px solid var(--ab-props-table-border); font-weight: 650; text-align: start; }
61
+ .abPropsTableGrid th,
62
+ .abPropsTableGrid td { padding: 12px 16px; border-block-end: 1px solid var(--ab-props-table-border); text-align: start; vertical-align: top; overflow-wrap: anywhere; }
63
+ .abPropsTableGrid thead th { background: color-mix(in srgb, var(--ab-props-table-text) 4%, transparent); color: var(--ab-props-table-muted); font-size: 12px; font-weight: 650; letter-spacing: 0.025em; }
64
+ .abPropsTableGrid tbody tr:last-child > * { border-block-end: 0; }
65
+ .abPropsTableName code,
66
+ .abPropsTableCode code { font: 13px/1.55 var(--ab-font-code, ui-monospace, monospace); overflow-wrap: anywhere; word-break: normal; }
67
+ .abPropsTableName code { color: var(--ab-props-table-text); font-weight: 650; }
68
+ .abPropsTableCode code { color: var(--ab-props-table-code); }
69
+ .abPropsTableRequired,
70
+ .abPropsTableDeprecated { display: block; margin-block-start: 4px; font-size: 11px; font-weight: 500; }
71
+ .abPropsTableRequired { color: var(--ab-color-danger, #904a43); }
72
+ .abPropsTableDeprecated,
73
+ .abPropsTableUnknown,
74
+ .abPropsTableNone { color: var(--ab-props-table-muted); }
75
+ .abPropsTableDeprecated { font-style: italic; }
76
+ .abPropsTableDescription { min-inline-size: 0; }
77
+ /* 🌙 Explicit dark containers (theme selectors are intentionally accepted at any ancestor). */
78
+ :where([data-theme='dark'], [data-color-scheme='dark'], [data-ab-theme='dark']) .abPropsTable {
79
+ --ab-props-table-surface: var(--ab-color-card, #211a16);
80
+ --ab-props-table-text: var(--ab-color-text, #f4ece5);
81
+ --ab-props-table-muted: var(--ab-color-muted, #c4b6ab);
82
+ --ab-props-table-border: var(--ab-color-border, rgb(244 236 229 / 0.18));
83
+ --ab-props-table-code: var(--ab-color-accent-text, #e5bc92);
84
+ }
85
+ /* 🌙 No theme provider is required: fallbacks also honor the operating system's dark preference. */
86
+ @media (prefers-color-scheme: dark) {
87
+ :root:not([data-theme='light']):not([data-color-scheme='light']):not([data-ab-theme='light']) .abPropsTable {
88
+ --ab-props-table-surface: var(--ab-color-card, #211a16);
89
+ --ab-props-table-text: var(--ab-color-text, #f4ece5);
90
+ --ab-props-table-muted: var(--ab-color-muted, #c4b6ab);
91
+ --ab-props-table-border: var(--ab-color-border, rgb(244 236 229 / 0.18));
92
+ --ab-props-table-code: var(--ab-color-accent-text, #e5bc92);
93
+ }
94
+ }
95
+ /* 🕶️ Keep status captions in the accessibility tree while removing them from the visual layout. */
96
+ .srOnly { position: absolute; inline-size: 1px; block-size: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
package/index.ts CHANGED
@@ -148,6 +148,7 @@ const supportedComponents: Array<ComponentCatalogEntry> = [
148
148
  { name: 'AbContentTab', file: 'ab-content-tabs/index.tsx', kind: 'client', status: 'Done' }, // 🗂️ 0.3.4 (0.2.24 MDX docs): AbContentTabs + AbContentTab (MDX <Tabs>/<Tab>)
149
149
  { name: 'AbCodeBlock', file: 'ab-code-block/index.tsx', kind: 'server', status: 'Done' }, // 💻 0.3.4 (0.2.24 MDX docs): AbCodeBlock (+ its copy island)
150
150
  { name: 'AbCallout', file: 'ab-callout/index.tsx', kind: 'server', status: 'Done' }, // 💡 0.3.4 (0.2.24 MDX docs): AbCallout
151
+ { name: 'AbPropsTable', file: 'ab-props-table/index.tsx', kind: 'server', status: 'Done' }, // 📋 unreleased: build-time docs prop data
151
152
  { name: 'AbList', file: 'ab-list/index.tsx', kind: 'server', status: 'Done' },
152
153
  ]
153
154
 
@@ -274,3 +275,7 @@ export type { AbContentTabsProps, AbContentTabProps } from './ab-content-tabs/in
274
275
  // ⏮️⏭️ 0.3.4 (0.2.24 MDX docs): AbDocPager
275
276
  export { default as AbDocPager } from './ab-doc-pager/index.tsx'
276
277
  export type { AbDocPagerProps, AbDocPagerLink } from './ab-doc-pager/index.tsx'
278
+
279
+ // 📋 AbPropsTable: a server-safe docs prop table built from structured extraction data.
280
+ export { default as AbPropsTable, AB_PROPS_TABLE_DEFAULT_LABELS } from './ab-props-table/index.tsx'
281
+ export type { AbPropsTableDefault, AbPropsTableDefaultNone, AbPropsTableDefaultUnknown, AbPropsTableDefaultValue, AbPropsTableLabels, AbPropsTableColumn, AbPropsTableProps, AbPropsTableRow } from './ab-props-table/index.tsx'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ab-nextjs-components",
3
- "version": "0.6.0",
3
+ "version": "0.7.1",
4
4
  "description": "🚀 A lightweight collection of server & client React components created by Abraham Ukachi, and optimized for Next.js applications 😎.",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -146,7 +146,8 @@
146
146
  "ab-callout",
147
147
  "ab-code-block",
148
148
  "ab-content-tabs",
149
- "ab-doc-pager"
149
+ "ab-doc-pager",
150
+ "ab-props-table"
150
151
  ],
151
152
  "exports": {
152
153
  ".": {
@@ -252,7 +253,8 @@
252
253
  "./ab-code-block": "./ab-code-block/index.tsx",
253
254
  "./ab-code-block/copy": "./ab-code-block/copy.tsx",
254
255
  "./ab-content-tabs": "./ab-content-tabs/index.tsx",
255
- "./ab-doc-pager": "./ab-doc-pager/index.tsx"
256
+ "./ab-doc-pager": "./ab-doc-pager/index.tsx",
257
+ "./ab-props-table": "./ab-props-table/index.tsx"
256
258
  },
257
259
  "peerDependenciesMeta": {
258
260
  "ab-nextjs-theme": {
package/types/index.d.ts CHANGED
@@ -154,3 +154,7 @@ export type { AbContentTabsProps, AbContentTabProps } from '../ab-content-tabs/i
154
154
  // ⏮️⏭️ 0.3.4 (0.2.24 MDX docs): AbDocPager
155
155
  export { default as AbDocPager } from '../ab-doc-pager/index.tsx';
156
156
  export type { AbDocPagerProps, AbDocPagerLink } from '../ab-doc-pager/index.tsx';
157
+
158
+ // 📋 AbPropsTable: available from both the root and `ab-nextjs-components/ab-props-table`.
159
+ export { default as AbPropsTable, AB_PROPS_TABLE_DEFAULT_LABELS } from '../ab-props-table/index.tsx';
160
+ export type { AbPropsTableDefault, AbPropsTableDefaultNone, AbPropsTableDefaultUnknown, AbPropsTableDefaultValue, AbPropsTableLabels, AbPropsTableColumn, AbPropsTableProps, AbPropsTableRow } from '../ab-props-table/index.tsx';