ab-nextjs-components 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -59,6 +59,8 @@ import close from 'ab-nextjs-icons/ab-icons/icons/close'; // ✖️ AbPage aside
59
59
  import expandMore from 'ab-nextjs-icons/ab-icons/icons/expand_more'; // 🔽 AbLocaleSwitcher no-JS list (0.1.13)
60
60
  import doubleLeft from 'ab-nextjs-icons/ab-icons/icons/keyboard_double_arrow_left'; // ⏪ AbSidebar outlined collapse (0.1.14, P9)
61
61
  import doubleRight from 'ab-nextjs-icons/ab-icons/icons/keyboard_double_arrow_right'; // ⏩ AbSidebar outlined expand (0.1.14, P9)
62
+ import refresh from 'ab-nextjs-icons/ab-icons/icons/refresh'; // 🔄 0.6.0 AbPreviewCode reload
63
+ import openInNew from 'ab-nextjs-icons/ab-icons/icons/open_in_new'; // ↗️ 0.6.0 AbPreviewCode open in a new tab
62
64
  // 🧾 shape
63
65
  import type { AbIconSvgData } from './helpers';
64
66
 
@@ -86,4 +88,6 @@ export const AB_ICON_BUILTINS: Record<string, AbIconSvgData> = {
86
88
  expand_more: expandMore, // 🔽
87
89
  keyboard_double_arrow_left: doubleLeft, // ⏪
88
90
  keyboard_double_arrow_right: doubleRight, // ⏩
91
+ refresh, // 🔄 0.6.0
92
+ open_in_new: openInNew, // ↗️ 0.6.0
89
93
  };
@@ -0,0 +1,115 @@
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: AbPreviewCode (G16, 0.6.0)
28
+ * @file: ab-preview-code/index.tsx
29
+ * @type: Server component (AbContentTabs + the copy button are the only client islands)
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ *
32
+ * Example usage (MDX):
33
+ * 1+|> <AbPreviewCode label="Button" code={`<AbButton label="Save" />`}>
34
+ * -|> <AbButton label="Save" />
35
+ * -|> </AbPreviewCode>
36
+ */
37
+
38
+ /*
39
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40
+ * MOTTO: We'll always do more 😜!!!
41
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
42
+ */
43
+
44
+ // ⚛️ React
45
+ import type { ReactElement, ReactNode } from 'react';
46
+ // 🧵 classes
47
+ import clsx from 'clsx';
48
+ // 🗂️ WAI-ARIA tabs (client island)
49
+ import AbContentTabs, { AbContentTab } from '../ab-content-tabs';
50
+ // 🧪 the preview scope's scheme type
51
+ import type { AbDemoBoxScheme } from '../ab-demo-box';
52
+ // 🧰 0.6.0: the toolbar + preview (a small client island; this file stays server-safe)
53
+ import AbPreviewStage from './stage';
54
+ // 💻 the source half
55
+ import AbDemoCode from '../ab-demo-code';
56
+ // 🎨 styles
57
+ import styles from './styles.module.css';
58
+
59
+ /** 🌍 translatable strings */
60
+ export interface AbPreviewCodeLabels {
61
+ preview?: string; // 🧪 the Preview tab (default "Preview")
62
+ code?: string; // 💻 the Code tab (default "Code")
63
+ copy?: string; // 📋 the copy button (default "Copy code")
64
+ copied?: string; // ✅ announced after a copy (default "Copied")
65
+ toolbar?: string; // 🧰 0.6.0: names the preview toolbar (default "Preview tools")
66
+ dark?: string; // 🌙 0.6.0: the scheme toggle (default "Dark preview", aria-pressed = dark)
67
+ reload?: string; // 🔄 0.6.0: the remount button (default "Reload preview")
68
+ open?: string; // ↗️ 0.6.0: the open-in-new-tab link (default "Open preview in a new tab")
69
+ }
70
+
71
+ /** ⚙️ props */
72
+ export interface AbPreviewCodeProps {
73
+ children: ReactNode; // 🧪 the live preview: real JSX with package components (D-c: no eval, no live editor)
74
+ code: string; // 📋 the matching source: shown plain when there is no `trustedHtml` / `highlighted`, always what Copy copies
75
+ trustedHtml?: string; // 🧾 Shiki `codeToHtml(code)` output, ⚠️ NOT sanitized: trusted HTML only, never user input (prefer `highlighted`)
76
+ highlighted?: ReactNode; // 🖍️ OR an already highlighted <pre> (e.g. an MDX fenced block)
77
+ language?: string; // 🔤 default 'tsx'
78
+ filename?: string; // 📄 shown in the code header
79
+ label?: string; // ♿ names the tablist, e.g. "Button example" (default "Example")
80
+ labels?: AbPreviewCodeLabels; // 🌍
81
+ defaultTab?: 'preview' | 'code'; // 🎯 default 'preview'
82
+ scheme?: AbDemoBoxScheme; // 🌗 force the preview's scheme (default: follow the page)
83
+ align?: 'center' | 'start' | 'stretch'; // 📐 the preview's alignment (default 'center')
84
+ toolbar?: boolean; // 🧰 0.6.0: the preview toolbar (light/dark toggle + reload [+ open]); default true
85
+ href?: string; // ↗️ 0.6.0: a standalone page for this example → an open-in-new-tab link in the toolbar
86
+ className?: string; // 🏷️
87
+ }
88
+
89
+ /**
90
+ * 🧪💻 AbPreviewCode — the docs Preview / Code pair (G16): AbContentTabs over an AbDemoBox preview scope and an
91
+ * AbDemoCode source block. Both panels are in the server HTML (the inactive one `hidden`), so the preview's
92
+ * markup and the code are crawlable and work before hydration. The preview is the children you pass, rendered
93
+ * as-is: nothing is parsed or evaluated from `code`, so keep the two in sync (a test can compare them).
94
+ */
95
+ const AbPreviewCode = ({ children, code, trustedHtml, highlighted, language = 'tsx', filename, label = 'Example', labels = {}, defaultTab = 'preview', scheme, align, toolbar = true, href, className }: AbPreviewCodeProps): ReactElement => {
96
+ const L = { preview: 'Preview', code: 'Code', copy: 'Copy code', copied: 'Copied', ...labels }; // 🌍
97
+ const stageLabels = { toolbar: L.toolbar, dark: L.dark, reload: L.reload, open: L.open }; // 🧰 undefined → the island's defaults
98
+ return (
99
+ <div className={clsx('AbPreviewCode', styles.abPreviewCode, className)} data-ab-part="preview-code">
100
+ <AbContentTabs label={label} defaultValue={defaultTab}>
101
+ <AbContentTab label={L.preview} value="preview">
102
+ {/* 🧪 the tabpanel already names it (aria-labelledby the tab), so the box needs no region role */}
103
+ <AbPreviewStage scheme={scheme} align={align} href={href} toolbar={toolbar} labels={stageLabels} className={styles.abPreviewCodeBox}>{children}</AbPreviewStage>
104
+ </AbContentTab>
105
+ <AbContentTab label={L.code} value="code">
106
+ <AbDemoCode code={code} trustedHtml={trustedHtml} language={language} filename={filename} copyLabel={L.copy} copiedLabel={L.copied}>{highlighted}</AbDemoCode>
107
+ </AbContentTab>
108
+ </AbContentTabs>
109
+ </div>
110
+ );
111
+ };
112
+
113
+ // 📦 exports
114
+ export default AbPreviewCode;
115
+ export { AbPreviewCode };
@@ -0,0 +1,153 @@
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: AbPreviewStage (0.6.0)
28
+ * @file: ab-preview-code/stage.tsx
29
+ * @type: Client component (island)
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+ */
32
+
33
+ /*
34
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35
+ * MOTTO: We'll always do more 😜!!!
36
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37
+ */
38
+
39
+ 'use client';
40
+
41
+ 'use client';
42
+
43
+ // ⚛️ React
44
+ import { useRef, useState, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
45
+ // 🧵 classes
46
+ import clsx from 'clsx';
47
+ // 🔣 icons (ab-nextjs-icons built-ins: dark_mode, light_mode, refresh, open_in_new)
48
+ import AbIcon from '../ab-icon';
49
+ // 🧪 the preview scope (server-safe, fine inside a client island)
50
+ import AbDemoBox, { type AbDemoBoxScheme } from '../ab-demo-box';
51
+ // 🎨 styles
52
+ import styles from './styles.module.css';
53
+
54
+ /** 🌍 the toolbar's translatable names */
55
+ export interface AbPreviewStageLabels {
56
+ toolbar?: string; // ♿ names the toolbar (default "Preview tools")
57
+ dark?: string; // 🌙 the scheme toggle, a pressed-state button (default "Dark preview")
58
+ reload?: string; // 🔄 the remount button (default "Reload preview")
59
+ open?: string; // ↗️ the open-in-new-tab link (default "Open preview in a new tab")
60
+ }
61
+
62
+ /** ⚙️ props */
63
+ export interface AbPreviewStageProps {
64
+ children?: ReactNode; // 🧪 the live preview (server-rendered JSX passes straight through)
65
+ scheme?: AbDemoBoxScheme; // 🌗 the starting scheme (default 'inherit'); the toggle then forces light / dark
66
+ align?: 'center' | 'start' | 'stretch'; // 📐 forwarded to AbDemoBox
67
+ href?: string; // ↗️ shows an "open in a new tab" link (target _blank, rel noopener noreferrer)
68
+ toolbar?: boolean; // 🧰 show the toolbar (default true); false = just the box
69
+ labels?: AbPreviewStageLabels; // 🌍
70
+ className?: string; // 🏷️ on the AbDemoBox
71
+ }
72
+
73
+ /**
74
+ * 🧰 AbPreviewStage — the small client island behind AbPreviewCode's preview: a WAI-ARIA toolbar (one tab stop,
75
+ * ←/→/Home/End move between tools) over an AbDemoBox.
76
+ * - 🌗 a light/dark toggle (`aria-pressed` = dark) that changes ONLY this preview's scheme (AbDemoBox `data-theme`)
77
+ * - 🔄 reload: remounts the preview with a key bump (state, timers and animations start fresh)
78
+ * - ↗️ with `href`: an open-in-new-tab link
79
+ * Every tool is a ≥44px target with an overridable aria-label. No motion here (motion lives in ab-nextjs-animations).
80
+ */
81
+ const AbPreviewStage = ({ children, scheme = 'inherit', align, href, toolbar = true, labels = {}, className }: AbPreviewStageProps): ReactElement => {
82
+ const L = { toolbar: 'Preview tools', dark: 'Dark preview', reload: 'Reload preview', open: 'Open preview in a new tab', ...Object.fromEntries(Object.entries(labels).filter(([, v]) => v != null)) }; // 🌍 undefined keeps the default
83
+ const [current, setCurrent] = useState<AbDemoBoxScheme>(scheme); // 🌗 this preview only
84
+ const [key, setKey] = useState(0); // 🔄 bumped → AbDemoBox remounts
85
+ const [active, setActive] = useState(0); // 🎯 roving tab stop (index of the focusable tool)
86
+ const bar = useRef<HTMLDivElement>(null); // 🧰
87
+ const dark = current === 'dark'; // 🌙 pressed?
88
+
89
+ /** ⌨️ APG toolbar keys: ←/→ wrap, Home/End jump; only the active tool is in the tab order */
90
+ const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
91
+ const tools = Array.from(bar.current?.querySelectorAll<HTMLElement>('[data-ab-tool]') ?? []); // 🔘 the tools
92
+ const i = tools.indexOf(document.activeElement as HTMLElement); // 📍
93
+ if (i < 0) return; // 🙅 focus is elsewhere
94
+ const n = tools.length; // 🔢
95
+ const next = e.key === 'ArrowRight' ? (i + 1) % n : e.key === 'ArrowLeft' ? (i - 1 + n) % n : e.key === 'Home' ? 0 : e.key === 'End' ? n - 1 : -1; // 🧭
96
+ if (next < 0) return; // ⏭️ other keys pass through
97
+ e.preventDefault(); // 🛑 no page scroll
98
+ setActive(next); // 🎯
99
+ tools[next]?.focus(); // ⌨️
100
+ };
101
+ const tab = (i: number) => (i === active ? 0 : -1); // 🎯 roving tabindex
102
+
103
+ return (
104
+ <div className={styles.abPreviewStage} data-ab-part="preview-stage">
105
+ {toolbar && (
106
+ <div ref={bar} role="toolbar" aria-label={L.toolbar} className={styles.abPreviewToolbar} data-ab-part="preview-toolbar" onKeyDown={onKeyDown}>
107
+ <button
108
+ type="button"
109
+ data-ab-tool="scheme" // 🌗
110
+ className={styles.abPreviewTool}
111
+ aria-label={L.dark} // ♿ the name stays; the state is aria-pressed
112
+ aria-pressed={dark} // 🌙 true = dark preview
113
+ tabIndex={tab(0)}
114
+ onFocus={() => setActive(0)}
115
+ onClick={() => setCurrent(dark ? 'light' : 'dark')} // 🔁 light ⇄ dark (from 'inherit' → dark first)
116
+ >
117
+ <AbIcon name={dark ? 'dark_mode' : 'light_mode'} size={20} /> {/* 🌞/🌙 decorative */}
118
+ </button>
119
+ <button
120
+ type="button"
121
+ data-ab-tool="reload" // 🔄
122
+ className={styles.abPreviewTool}
123
+ aria-label={L.reload}
124
+ tabIndex={tab(1)}
125
+ onFocus={() => setActive(1)}
126
+ onClick={() => setKey((k) => k + 1)} // 🔑 key bump → remount
127
+ >
128
+ <AbIcon name="refresh" size={20} />
129
+ </button>
130
+ {href && (
131
+ <a
132
+ href={href}
133
+ target="_blank" // ↗️ new tab
134
+ rel="noopener noreferrer" // 🔐 no window.opener, no referrer
135
+ data-ab-tool="open"
136
+ className={styles.abPreviewTool}
137
+ aria-label={L.open}
138
+ tabIndex={tab(2)}
139
+ onFocus={() => setActive(2)}
140
+ >
141
+ <AbIcon name="open_in_new" size={20} />
142
+ </a>
143
+ )}
144
+ </div>
145
+ )}
146
+ <AbDemoBox key={key} scheme={current} align={align} className={className}>{children}</AbDemoBox>
147
+ </div>
148
+ );
149
+ };
150
+
151
+ // 📦 exports
152
+ export default AbPreviewStage;
153
+ export { AbPreviewStage };
@@ -0,0 +1,43 @@
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-preview-code/styles.module.css
29
+ * @type: CSS Stylesheet
30
+ * @authors: Abraham Ukachi <abrahamukachi@gmail.com>
31
+
32
+ /* 🧪💻 the pair: one block in the prose rhythm; the tabs' own bottom margin is dropped inside it */
33
+ .abPreviewCode { margin: 0 0 1.25em; min-inline-size: 0; } /* ↕️ + ↔️ never widens the page */
34
+ .abPreviewCode > :global(.AbContentTabs) { margin: 0; } /* ↕️ */
35
+ .abPreviewCodeBox { min-block-size: 180px; } /* 📏 room for a menu / drawer demo */
36
+
37
+ /* 🧰 0.6.0: the preview toolbar (AbPreviewStage) — tools end-aligned above the box */
38
+ .abPreviewStage { display: grid; min-inline-size: 0; } /* 📐 */
39
+ .abPreviewToolbar { display: flex; justify-content: flex-end; gap: 4px; padding: 2px; } /* 🧰 */
40
+ .abPreviewTool { display: inline-flex; align-items: center; justify-content: center; min-inline-size: 44px; min-block-size: 44px; padding: 0; border: 0; border-radius: 10px; background: transparent; color: inherit; cursor: pointer; } /* 🔘 ≥44px targets */
41
+ .abPreviewTool:hover { background: var(--ab-color-hover, rgb(92 64 48 / 0.08)); } /* 🖱️ */
42
+ .abPreviewTool:focus-visible { outline: 2px solid var(--ab-color-accent, #a67c52); outline-offset: 2px; } /* ♿ */
43
+ .abPreviewTool[aria-pressed='true'] { background: var(--ab-color-selected, rgb(92 64 48 / 0.14)); } /* 🌙 pressed */
@@ -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; }