@cosborn2/ui 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +163 -0
  3. package/dist/_escape-layer.d.ts +7 -0
  4. package/dist/_escape-layer.js +63 -0
  5. package/dist/_portal-theme.d.ts +3 -0
  6. package/dist/_portal-theme.js +35 -0
  7. package/dist/_settings-navigation.d.ts +25 -0
  8. package/dist/_settings-navigation.js +10 -0
  9. package/dist/actions-menu.d.ts +29 -0
  10. package/dist/actions-menu.js +55 -0
  11. package/dist/button.d.ts +9 -0
  12. package/dist/button.js +9 -0
  13. package/dist/color-picker.d.ts +16 -0
  14. package/dist/color-picker.js +7 -0
  15. package/dist/confirm-dialog.d.ts +17 -0
  16. package/dist/confirm-dialog.js +16 -0
  17. package/dist/data-table.d.ts +24 -0
  18. package/dist/data-table.js +28 -0
  19. package/dist/expandable-pill.d.ts +12 -0
  20. package/dist/expandable-pill.js +47 -0
  21. package/dist/ghost-text-button.d.ts +3 -0
  22. package/dist/ghost-text-button.js +4 -0
  23. package/dist/glass-popover-surface.d.ts +9 -0
  24. package/dist/glass-popover-surface.js +4 -0
  25. package/dist/header-shell.d.ts +21 -0
  26. package/dist/header-shell.js +22 -0
  27. package/dist/icon-button.d.ts +7 -0
  28. package/dist/icon-button.js +4 -0
  29. package/dist/input.d.ts +7 -0
  30. package/dist/input.js +8 -0
  31. package/dist/modal.d.ts +26 -0
  32. package/dist/modal.js +55 -0
  33. package/dist/notice.d.ts +10 -0
  34. package/dist/notice.js +5 -0
  35. package/dist/pagination.d.ts +30 -0
  36. package/dist/pagination.js +19 -0
  37. package/dist/pill.d.ts +12 -0
  38. package/dist/pill.js +12 -0
  39. package/dist/segmented-control.d.ts +18 -0
  40. package/dist/segmented-control.js +8 -0
  41. package/dist/select.d.ts +8 -0
  42. package/dist/select.js +9 -0
  43. package/dist/settings-rail.d.ts +11 -0
  44. package/dist/settings-rail.js +7 -0
  45. package/dist/settings.d.ts +56 -0
  46. package/dist/settings.js +25 -0
  47. package/dist/skeleton.d.ts +3 -0
  48. package/dist/skeleton.js +4 -0
  49. package/dist/styles/actions-menu.css +13 -0
  50. package/dist/styles/all.css +25 -0
  51. package/dist/styles/button.css +18 -0
  52. package/dist/styles/color-picker.css +11 -0
  53. package/dist/styles/confirm-dialog.css +8 -0
  54. package/dist/styles/data-table.css +15 -0
  55. package/dist/styles/expandable-pill.css +10 -0
  56. package/dist/styles/ghost-text-button.css +7 -0
  57. package/dist/styles/glass-popover-surface.css +5 -0
  58. package/dist/styles/header-shell.css +4 -0
  59. package/dist/styles/icon-button.css +11 -0
  60. package/dist/styles/input.css +11 -0
  61. package/dist/styles/modal.css +19 -0
  62. package/dist/styles/notice.css +14 -0
  63. package/dist/styles/pagination.css +18 -0
  64. package/dist/styles/pill.css +3 -0
  65. package/dist/styles/segmented-control.css +11 -0
  66. package/dist/styles/select.css +12 -0
  67. package/dist/styles/settings-rail.css +1 -0
  68. package/dist/styles/settings.css +434 -0
  69. package/dist/styles/skeleton.css +5 -0
  70. package/dist/styles/surface.css +6 -0
  71. package/dist/styles/switch.css +14 -0
  72. package/dist/styles/theme-toggle.css +9 -0
  73. package/dist/styles/theme.css +80 -0
  74. package/dist/styles/toast.css +22 -0
  75. package/dist/surface.d.ts +5 -0
  76. package/dist/surface.js +4 -0
  77. package/dist/switch.d.ts +8 -0
  78. package/dist/switch.js +10 -0
  79. package/dist/theme-toggle.d.ts +10 -0
  80. package/dist/theme-toggle.js +12 -0
  81. package/dist/toast.d.ts +38 -0
  82. package/dist/toast.js +17 -0
  83. package/dist/tokens.json +84 -0
  84. package/package.json +186 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 @cosborn2/ui contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,163 @@
1
+ # @cosborn2/ui
2
+
3
+ React 19 components for web applications: controls, glass surfaces, accessible dialogs, and settings layouts. MIT licensed. ESM with TypeScript declarations.
4
+
5
+ The package works without Tailwind, a theme provider, Next.js, or a CSS-in-JS runtime. Import each component and its CSS explicitly. There is intentionally no root JavaScript barrel.
6
+
7
+ ## Install and render a button
8
+
9
+ Install the `beta` tag or an explicit version for prereleases. Stable releases use the default `latest` tag.
10
+
11
+ ```sh
12
+ npm install @cosborn2/ui@beta react react-dom
13
+ ```
14
+
15
+ ```tsx
16
+ import '@cosborn2/ui/theme.css';
17
+ import '@cosborn2/ui/button.css';
18
+ import { Button } from '@cosborn2/ui/button';
19
+
20
+ export function SaveButton() {
21
+ return <Button type="submit">Save changes</Button>;
22
+ }
23
+ ```
24
+
25
+ In Next App Router, the example can run as a Server Component. Event handlers belong in a client component; native form submission does not require an event handler. Button preserves the native default `type="submit"`, so specify `type="button"` for non-submit actions inside forms.
26
+
27
+ Import `theme.css` once, normally at the app's CSS entry or root layout. Import component styles there or alongside the component's app-owned adapter. JS entry points contain no CSS imports, so they also work with plain Node SSR. `all.css` is available when intentionally loading every component's styles; prefer individual styles for small consumers.
28
+
29
+ ## Components and rendering boundaries
30
+
31
+ Each entry exports its prop types. Every entry has a matching `.css` export.
32
+
33
+ | Entry | Exports | Rendering |
34
+ | --- | --- | --- |
35
+ | `button` | `Button`, `buttonClassName` for anchors/router links | Server-compatible |
36
+ | `icon-button` | `IconButton` | Server-compatible |
37
+ | `ghost-text-button` | `GhostTextButton` | Server-compatible |
38
+ | `input`, `select` | `Input`, native `Select` | Server-compatible |
39
+ | `switch` | `Switch` (native checkbox) | Server-compatible |
40
+ | `skeleton` | `Skeleton` | Server-compatible |
41
+ | `pill` | `Pill` | Server-compatible |
42
+ | `surface` | `Surface` | Server-compatible |
43
+ | `glass-popover-surface` | `GlassPopoverSurface` | Server-compatible |
44
+ | `header-shell` | `HeaderShell`, padding constants | Server-compatible |
45
+ | `data-table` | `DataTable`, typed columns, loading/empty states | Server-compatible; callbacks require a client caller |
46
+ | `pagination` | `Pagination`, `PAGE_SIZE` | Server-compatible links; callbacks require a client caller |
47
+ | `settings` | `SettingsLayout`, `SettingsPageHeader`, `SettingsCard`, `SettingsCardHeader`, `SettingsRow`, `SettingsSection`, `SettingsNavigation` | Server-compatible |
48
+ | `settings-rail` | `SettingsRail` | Client boundary for callback navigation |
49
+ | `expandable-pill` | `ExpandablePill` | Client boundary |
50
+ | `segmented-control` | `SegmentedControl` | Client boundary |
51
+ | `theme-toggle`, `color-picker` | Controlled `ThemeToggle`, configurable `ColorPicker` | Client boundaries |
52
+ | `notice` | `Notice` with neutral/success/danger tones and optional heading/icon/actions | Server-compatible |
53
+ | `toast` | Controlled `Toast`, `ToastViewport` presentation | Server-compatible; handlers require a client caller |
54
+ | `actions-menu` | `ActionsMenu`, typed actions | Client boundary |
55
+ | `modal`, `confirm-dialog` | `Modal`, `ConfirmDialog` | Client boundary |
56
+
57
+ “Server-compatible” means the same component can be imported into a Server Component or ordinary client React code. It does not prohibit client use or imply a `server-only` dependency. Interactive entries preserve their own `"use client"` directives in the published modules. No page-wide client wrapper is required.
58
+
59
+ `DataTable` renders native table markup. Supply `getRowKey` for stable row identity, `caption` for a visible accessible table name, and `columns` with cell render functions. Static cell render functions execute on the server. For row actions, prefer links/buttons in cells; optional `onRowClick` supports Enter/Space activation when used inside a client component. Optional `onRowIntent(row)` runs on pointer entry or focus within a row, allowing the application to prefetch details. These callbacks require a client caller; static tables add no row event handlers when the callbacks are omitted.
60
+
61
+ `Pagination` renders real navigation links with `getPageHref={(page) => "/records?page=" + page}` and works without JavaScript. For local state, pass `onPageChange` from a client component instead. Page indexes start at zero; `pageSize` defaults to 20. Both components import only their own supporting styles through their matching CSS entry.
62
+
63
+ `ThemeToggle` accepts `value` (`system`, `light`, or `dark`) and `onChange`; it does not read storage or change document attributes. `ColorPicker` accepts `value`, `onChange`, and a `colors` array of `{ value, label, disabled? }`. Its optional empty selection returns `null`; set `allowNone={false}` to omit it. These controls expose accessible labels/selection and never submit an enclosing form. The application owns persistence and its color palette.
64
+
65
+ ## Notices, menus, and notifications
66
+
67
+ `Notice` displays inline feedback with `tone="neutral"`, `"success"`, or `"danger"`. It accepts `heading`, decorative `icon`, `actions`, children, and native div attributes/ref. Static notices do not announce themselves. Choose `role="alert"` for an urgent form error or `role="status"` for a polite update when appropriate. Import `notice.css`.
68
+
69
+ `ActionsMenu` accepts `items` with `label`, `onClick`, and optional `id`, `icon`, `disabled`, and `variant="danger"`. Give the trigger a contextual `ariaLabel`, such as "Actions for Alex". The default trigger uses Lucide Ellipsis; an optional `trigger` element must forward its ref and native button props. Keyboard navigation, typeahead, disabled-item skipping, collision handling, dismissal, and focus restoration use Radix Dropdown Menu. `open`/`onOpenChange` or `defaultOpen`, `align`, `sideOffset`, `collisionPadding`, `portalContainer`, and `theme` allow customization. Import `actions-menu.css`. Menus inherit tokens from their trigger region and coordinate Escape with shared dialogs.
70
+
71
+ `Toast` and `ToastViewport` are presentation components with no notification store, provider, or timer. Pass `message`, `variant="success" | "error" | "info"`, optional `action`, `onDismiss`, and controlled `progress` (remaining fraction from 0 to 1). Import `toast.css`. Applications decide duration, queuing, persistence, and when to remove a notification. A timed host should pause expiry while hovered or while focus is within a toast. Pass native pointer/focus handlers to implement that policy. The message is announced separately from controls and the decorative progress ring. `announce` defaults to `"assertive"` for errors and `"polite"` otherwise; use `"off"` for non-announcing presentation. Use a meaningful `dismissLabel` when needed.
72
+
73
+ Keep the viewport mounted when empty. For dynamically added notifications, pass `announcements={{ polite, assertive }}` with keyed message-only children, and use `announce="off"` on each visual Toast. This creates persistent live regions before additions arrive, while omitting action labels, progress changes, and removals from announcements. The app adapters demonstrate this pattern. The visual stack scrolls when it fills its available height; override `--bnh-toast-bottom`, `--bnh-toast-z`, or native styles for app chrome offsets.
74
+
75
+ ## Dialogs
76
+
77
+ ```tsx
78
+ 'use client';
79
+
80
+ import { useState, type ReactNode } from 'react';
81
+ import { Button } from '@cosborn2/ui/button';
82
+ import { Modal } from '@cosborn2/ui/modal';
83
+ import '@cosborn2/ui/button.css';
84
+ import '@cosborn2/ui/modal.css';
85
+
86
+ export function DetailsDialog({ children }: { children: ReactNode }) {
87
+ const [open, setOpen] = useState(false);
88
+ return (
89
+ <Modal
90
+ open={open}
91
+ onOpenChange={setOpen}
92
+ title="Details"
93
+ trigger={<Button type="button">Show details</Button>}
94
+ >
95
+ {children}
96
+ </Modal>
97
+ );
98
+ }
99
+ ```
100
+
101
+ A Server Component can pass its rendered content as `children` to this client shell. Keep event handlers on the client side of the boundary.
102
+
103
+ Modal uses Radix Dialog for focus containment, screen-reader behavior, dismissal, and scroll locking. Give it a `title` or descriptive `ariaLabel`. `persistent` prevents dismissal while an operation is pending. `width` accepts a number in pixels or a CSS width; `zIndex`, `headerActions`, `footer`, `className`, and `bodyClassName` customize layout.
104
+
105
+ Portal content mounts after hydration, including when `open` starts true. The server and first browser render agree; dialog content is not promised in the initial server HTML. The trigger and surrounding server content render normally. No `ssr: false` is needed.
106
+
107
+ Dialogs inherit `--bnh-*` tokens from their rendering location even when portaled into the document body. Use `theme="light"` / `theme="dark"` for an explicit choice, or `portalContainer` for a custom mount location. Theme attribute/style changes on ancestors are observed while open.
108
+
109
+ `ConfirmDialog` adds cancel/confirm actions, optional loading state, and `typeToConfirm`. Its typed phrase resets when the dialog closes. Supply `children` for extra content such as a password field or verification notice, and `confirmDisabled` for application-owned prerequisites. Confirmation stays disabled while loading, while `confirmDisabled` is true, or until the typed phrase matches. The application owns validation and submission. Import `confirm-dialog.css`; it includes the button, input, and modal CSS it needs.
110
+
111
+ ## Theme and overrides
112
+
113
+ Dark is the default. Set `data-bnh-theme="light"` on the document or a region to use light mode. `data-bnh-theme="dark"`, `.bnh-theme-light`, `.bnh-theme-dark`, and the legacy document `.light` class are supported.
114
+
115
+ ```css
116
+ @import '@cosborn2/ui/theme.css';
117
+ @import '@cosborn2/ui/button.css';
118
+
119
+ :root {
120
+ --bnh-font-sans: 'Your Sans', system-ui, sans-serif;
121
+ --bnh-font-display: 'Your Display', Georgia, serif;
122
+ --bnh-accent: #8b5cf6;
123
+ }
124
+ ```
125
+
126
+ The apps own font loading, persistence, and system theme detection. The library downloads no fonts and installs no global reset. Colors, surfaces, radii, fonts, and header/page offsets are available as `--bnh-*` variables. The complete defaults are also exported as `@cosborn2/ui/tokens.json`.
127
+
128
+ CSS uses the layer order `theme, base, components, utilities`. Host resets belong in `base`; utility overrides belong in `utilities`; ordinary unlayered CSS also overrides package component styles. Existing Tailwind v4 projects can keep their own utility classes; no package source scanning is needed. Each component accepts appropriate `className`/`style` overrides, without loading a utility-class merger.
129
+
130
+ Settings layouts use `--bnh-page-offset` for a page-level banner and `--bnh-header-offset` for header placement. Applications supply those values; there is no impersonation or authentication dependency.
131
+
132
+ ## Icons and dependencies
133
+
134
+ Plain Button imports no icon or dialog code. Icons are passed as children or rendered slots. Components with built-in icons import only those glyphs. React and React DOM are peer dependencies; Radix Dialog, Radix Dropdown Menu, and the pinned Lucide release are runtime dependencies reachable only from components that use them.
135
+
136
+ Lucide `0.577.0` is pinned to preserve server-compatible static icons. Current Lucide v1 uses client context internally. Upgrade only after the server-rendering and bundle fixtures pass; do not replace direct imports with an all-icons registry.
137
+
138
+ Installing npm packages downloads their dependency distributions. Tree shaking controls the JS/CSS shipped to the browser, not which files npm downloads. The package tests report those sizes separately.
139
+
140
+ ## Development and verification
141
+
142
+ From the repository root:
143
+
144
+ ```sh
145
+ bun install --frozen-lockfile
146
+ bun run lint
147
+ bun run build
148
+ bun run test
149
+ bunx playwright install chromium
150
+ bun run test:browser
151
+ ```
152
+
153
+ The build emits separate ESM modules, declarations, and plain CSS. `dev` watches source and theme/style changes. The package fixtures install a packed tarball outside this repository and check Node SSR, production Next Server Components, browser hydration/accessibility, and compressed per-component JS/CSS budgets. Browser checks require Playwright Chromium and include the packed-package checks. Use `bun run test:package` when only the non-browser checks are needed.
154
+
155
+ Edit `tokens.json` for canonical theme changes, then run `bun run build` to regenerate the packaged theme. Applications own any compatibility aliases or infrastructure pages that consume these tokens. The library does not read application styles during its build.
156
+
157
+ ## Release
158
+
159
+ Versions are chosen in reviewed PRs. With trusted publishing configured, version changes merged to `main` publish after validation; prereleases use `beta` and stable releases use `latest`. See the [publishing runbook](https://github.com/COsborn2/ui/blob/main/docs/publishing.md) for setup, release checks, and retries.
160
+
161
+ The public npm package includes only `dist`, this README, the MIT license, and package metadata. Consumers adopt new versions through their own dependency updates.
162
+
163
+ For development and review expectations, see [CONTRIBUTING.md](https://github.com/COsborn2/ui/blob/main/CONTRIBUTING.md). Report vulnerabilities through the private channel in [SECURITY.md](https://github.com/COsborn2/ui/blob/main/SECURITY.md).
@@ -0,0 +1,7 @@
1
+ /** Synchronize shared overlays before Radix hands off its passive listeners. */
2
+ export declare function useEscapeLayer(open: boolean, dismiss: () => void, portalContainer?: HTMLElement | null): {
3
+ origin: import("react").RefObject<HTMLSpanElement | null>;
4
+ setOrigin: (node: HTMLSpanElement | null) => void;
5
+ onEscapeKeyDown: (event: Pick<KeyboardEvent, "defaultPrevented" | "preventDefault">) => void;
6
+ isTopLayer: (event?: Event) => boolean;
7
+ };
@@ -0,0 +1,63 @@
1
+ "use client";
2
+ import { useCallback, useRef, useState } from "react";
3
+ const escapeLayers = new WeakMap();
4
+ const interactionLayers = new WeakMap();
5
+ let nextEscapeLayerOrder = 0;
6
+ function register(layer, document) {
7
+ const layers = escapeLayers.get(document) ?? [];
8
+ // Ref refreshes retain their opening order, even if a lower layer re-renders.
9
+ if (!layer.order)
10
+ layer.order = ++nextEscapeLayerOrder;
11
+ const later = layers.findIndex((entry) => entry.order > layer.order);
12
+ layers.splice(later < 0 ? layers.length : later, 0, layer);
13
+ escapeLayers.set(document, layers);
14
+ layer.document = document;
15
+ }
16
+ function unregister(layer) {
17
+ const document = layer.document;
18
+ const layers = document && escapeLayers.get(document);
19
+ if (document && layers) {
20
+ layers.splice(layers.indexOf(layer), 1);
21
+ if (!layers.length)
22
+ escapeLayers.delete(document);
23
+ }
24
+ layer.document = undefined;
25
+ }
26
+ /** Synchronize shared overlays before Radix hands off its passive listeners. */
27
+ export function useEscapeLayer(open, dismiss, portalContainer) {
28
+ const origin = useRef(null);
29
+ const [layer] = useState(() => ({ order: 0, dismiss: () => { } }));
30
+ const setOrigin = useCallback((node) => {
31
+ origin.current = node;
32
+ unregister(layer);
33
+ if (!node)
34
+ return;
35
+ layer.dismiss = dismiss;
36
+ if (open)
37
+ register(layer, portalContainer?.ownerDocument ?? node.ownerDocument);
38
+ else
39
+ layer.order = 0;
40
+ }, [dismiss, layer, open, portalContainer]);
41
+ const isTopLayer = useCallback((event) => {
42
+ if (!layer.document)
43
+ return false;
44
+ const top = escapeLayers.get(layer.document)?.at(-1);
45
+ if (event && top && !interactionLayers.has(event))
46
+ interactionLayers.set(event, top);
47
+ // A deferred outside click must retain the owner it had on pointerdown,
48
+ // even if that child has closed by the time Radix delivers the click.
49
+ return (event ? interactionLayers.get(event) : top) === layer;
50
+ }, [layer]);
51
+ function onEscapeKeyDown(event) {
52
+ if (event.defaultPrevented || !layer.document)
53
+ return;
54
+ const top = escapeLayers.get(layer.document)?.at(-1);
55
+ if (!top)
56
+ return;
57
+ // Cancel before notifying a consumer that may synchronously unmount its
58
+ // overlay. One event must never dismiss both the child and its parent.
59
+ event.preventDefault();
60
+ top.dismiss();
61
+ }
62
+ return { origin, setOrigin, onEscapeKeyDown, isTopLayer };
63
+ }
@@ -0,0 +1,3 @@
1
+ import { type CSSProperties, type RefObject } from "react";
2
+ /** Copy scoped tokens across a portal and follow changes to its source region. */
3
+ export declare function usePortalTheme(origin: RefObject<HTMLElement | null>, open: boolean, theme?: "light" | "dark", portalContainer?: HTMLElement | null): CSSProperties;
@@ -0,0 +1,35 @@
1
+ "use client";
2
+ import { useLayoutEffect, useState } from "react";
3
+ /** Copy scoped tokens across a portal and follow changes to its source region. */
4
+ export function usePortalTheme(origin, open, theme, portalContainer) {
5
+ const [tokens, setTokens] = useState({});
6
+ useLayoutEffect(() => {
7
+ const marker = origin.current;
8
+ if (!open || !marker)
9
+ return;
10
+ const view = marker.ownerDocument.defaultView;
11
+ if (!view)
12
+ return;
13
+ const update = () => {
14
+ const computed = view.getComputedStyle(marker);
15
+ const values = {};
16
+ for (let index = 0; index < computed.length; index++) {
17
+ const name = computed.item(index);
18
+ if (name.startsWith("--bnh-"))
19
+ values[name] = computed.getPropertyValue(name);
20
+ }
21
+ setTokens((previous) => {
22
+ const old = previous;
23
+ return Object.keys(old).length === Object.keys(values).length && Object.entries(values).every(([key, value]) => old[key] === value)
24
+ ? previous : values;
25
+ });
26
+ };
27
+ update();
28
+ const observer = new view.MutationObserver(update);
29
+ for (let ancestor = marker; ancestor; ancestor = ancestor.parentElement) {
30
+ observer.observe(ancestor, { attributes: true, attributeFilter: ["class", "style", "data-bnh-theme"] });
31
+ }
32
+ return () => observer.disconnect();
33
+ }, [open, origin, theme, portalContainer]);
34
+ return tokens;
35
+ }
@@ -0,0 +1,25 @@
1
+ import type { ReactNode } from "react";
2
+ export interface RailItem {
3
+ id: string;
4
+ label: string;
5
+ icon?: ReactNode;
6
+ badge?: number | string;
7
+ /** Optional ID of the content controlled by this item. */
8
+ controls?: string;
9
+ }
10
+ export interface RailSection<Item extends RailItem = RailItem> {
11
+ group: string;
12
+ items: readonly Item[];
13
+ }
14
+ export declare function SettingsNavigationFrame({ children, label, className, }: {
15
+ children: ReactNode;
16
+ label?: string;
17
+ className?: string;
18
+ }): import("react").JSX.Element;
19
+ export declare function SettingsNavigationGroup({ group, children }: {
20
+ group: string;
21
+ children: ReactNode;
22
+ }): import("react").JSX.Element;
23
+ export declare function SettingsNavigationItemContent({ item }: {
24
+ item: RailItem;
25
+ }): import("react").JSX.Element;
@@ -0,0 +1,10 @@
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ export function SettingsNavigationFrame({ children, label = "Settings", className, }) {
3
+ return (_jsx("nav", { "aria-label": label, className: ["bnh-settings-rail", className].filter(Boolean).join(" "), children: _jsx("div", { className: "bnh-settings-rail-inner", children: children }) }));
4
+ }
5
+ export function SettingsNavigationGroup({ group, children }) {
6
+ return (_jsxs("div", { className: "bnh-settings-rail-section", children: [_jsx("div", { className: "bnh-settings-rail-group", children: group }), children] }));
7
+ }
8
+ export function SettingsNavigationItemContent({ item }) {
9
+ return (_jsxs(_Fragment, { children: [item.icon != null && _jsx("span", { className: "bnh-settings-rail-icon", "aria-hidden": "true", children: item.icon }), _jsx("span", { className: "bnh-settings-rail-label", children: item.label }), item.badge != null && _jsx("span", { className: "bnh-settings-rail-badge", children: item.badge })] }));
10
+ }
@@ -0,0 +1,29 @@
1
+ import { type ReactElement, type ReactNode } from "react";
2
+ export interface ActionItem {
3
+ id?: string;
4
+ label: string;
5
+ onClick: () => void;
6
+ variant?: "default" | "danger";
7
+ disabled?: boolean;
8
+ icon?: ReactNode;
9
+ }
10
+ export interface ActionsMenuProps {
11
+ items: readonly ActionItem[];
12
+ ariaLabel?: string;
13
+ /** A button that forwards its native props/ref, for example the shared Button. */
14
+ trigger?: ReactElement;
15
+ open?: boolean;
16
+ defaultOpen?: boolean;
17
+ onOpenChange?: (open: boolean) => void;
18
+ disabled?: boolean;
19
+ align?: "start" | "center" | "end";
20
+ sideOffset?: number;
21
+ collisionPadding?: number;
22
+ portalContainer?: HTMLElement | null;
23
+ theme?: "light" | "dark";
24
+ zIndex?: number;
25
+ className?: string;
26
+ triggerClassName?: string;
27
+ }
28
+ /** Accessible action menu with deferred portals, keyboard navigation and collision handling. */
29
+ export declare function ActionsMenu({ items, ariaLabel, trigger, open, defaultOpen, onOpenChange, disabled, align, sideOffset, collisionPadding, portalContainer, theme, zIndex, className, triggerClassName, }: ActionsMenuProps): import("react").JSX.Element;
@@ -0,0 +1,55 @@
1
+ "use client";
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
4
+ import { Ellipsis } from "lucide-react";
5
+ import { useCallback, useLayoutEffect, useRef, useState } from "react";
6
+ import { useEscapeLayer } from "./_escape-layer.js";
7
+ import { usePortalTheme } from "./_portal-theme.js";
8
+ /** Accessible action menu with deferred portals, keyboard navigation and collision handling. */
9
+ export function ActionsMenu({ items, ariaLabel, trigger, open, defaultOpen = false, onOpenChange, disabled = false, align = "end", sideOffset = 4, collisionPadding = 8, portalContainer, theme, zIndex, className, triggerClassName, }) {
10
+ const [internalOpen, setInternalOpen] = useState(defaultOpen);
11
+ const triggerRef = useRef(null);
12
+ const contentRef = useRef(null);
13
+ const handledOutside = useRef(null);
14
+ const unavailable = disabled || !items.length;
15
+ const isOpen = !unavailable && (open ?? internalOpen);
16
+ const changeOpen = useCallback((value) => {
17
+ if (open === undefined)
18
+ setInternalOpen(value);
19
+ onOpenChange?.(value);
20
+ }, [onOpenChange, open]);
21
+ const dismiss = useCallback(() => changeOpen(false), [changeOpen]);
22
+ const { origin, setOrigin, onEscapeKeyDown, isTopLayer } = useEscapeLayer(isOpen, dismiss, portalContainer);
23
+ const tokens = usePortalTheme(origin, isOpen, theme, portalContainer);
24
+ const style = { ...tokens, ...(zIndex === undefined ? {} : { "--bnh-actions-menu-z": zIndex }) };
25
+ useLayoutEffect(() => {
26
+ const document = portalContainer?.ownerDocument ?? origin.current?.ownerDocument;
27
+ if (!isOpen || !document)
28
+ return;
29
+ const pointerDown = (event) => {
30
+ const content = contentRef.current;
31
+ const target = event.target;
32
+ if (!target || !content || content.contains(target) || triggerRef.current?.contains(target)
33
+ || content.style.pointerEvents === "none" || !isTopLayer(event))
34
+ return;
35
+ // Radix defers attaching its outside-pointer listener until a later task.
36
+ // Defer past the whole event dispatch (microtasks can run between native
37
+ // listeners), then cover only an event its normal handler did not handle.
38
+ setTimeout(() => {
39
+ if (!event.defaultPrevented && handledOutside.current !== event
40
+ && contentRef.current && isTopLayer() && isTopLayer(event))
41
+ changeOpen(false);
42
+ }, 0);
43
+ };
44
+ document.addEventListener("pointerdown", pointerDown);
45
+ return () => document.removeEventListener("pointerdown", pointerDown);
46
+ }, [changeOpen, isOpen, isTopLayer, origin, portalContainer]);
47
+ return (_jsxs(DropdownMenu.Root, { open: isOpen, onOpenChange: changeOpen, children: [_jsx("span", { ref: setOrigin, hidden: true, "data-bnh-theme": theme }), _jsx(DropdownMenu.Trigger, { ref: triggerRef, asChild: Boolean(trigger), type: "button", disabled: unavailable, "aria-label": ariaLabel ?? (trigger ? undefined : "More actions"), className: [!trigger && "bnh-actions-menu-trigger", triggerClassName].filter(Boolean).join(" ") || undefined, onClick: (event) => event.stopPropagation(), onKeyDown: (event) => {
48
+ if (["Enter", " ", "ArrowDown", "ArrowUp"].includes(event.key))
49
+ event.stopPropagation();
50
+ }, children: trigger ?? _jsx(Ellipsis, { size: 16, "aria-hidden": "true" }) }), _jsx(DropdownMenu.Portal, { container: portalContainer ?? undefined, children: _jsx(DropdownMenu.Content, { ref: contentRef, className: ["bnh-actions-menu", className].filter(Boolean).join(" "), style: style, align: align, sideOffset: sideOffset, collisionPadding: collisionPadding, loop: true, onEscapeKeyDown: onEscapeKeyDown, onPointerDownOutside: (event) => { handledOutside.current = event.detail.originalEvent; }, onKeyDown: (event) => {
51
+ if (event.key === "Escape")
52
+ onEscapeKeyDown(event);
53
+ event.stopPropagation();
54
+ }, onClick: (event) => event.stopPropagation(), children: items.map((item, index) => (_jsxs(DropdownMenu.Item, { className: ["bnh-actions-menu-item", item.variant === "danger" && "bnh-actions-menu-item--danger"].filter(Boolean).join(" "), disabled: item.disabled, textValue: item.label, onSelect: () => item.onClick(), children: [item.icon && _jsx("span", { className: "bnh-actions-menu-icon", "aria-hidden": "true", children: item.icon }), _jsx("span", { children: item.label })] }, item.id ?? `${item.label}-${index}`))) }) })] }));
55
+ }
@@ -0,0 +1,9 @@
1
+ import type { ComponentPropsWithRef } from "react";
2
+ export interface ButtonProps extends ComponentPropsWithRef<"button"> {
3
+ variant?: "primary" | "secondary" | "ghost" | "danger";
4
+ size?: "sm" | "md" | "lg";
5
+ }
6
+ /** Apply the same presentation to an anchor or an application router link. */
7
+ export declare function buttonClassName({ variant, size, className }?: Pick<ButtonProps, "variant" | "size" | "className">): string;
8
+ /** A native button. Set type="button" when it must not submit a form. */
9
+ export declare function Button({ className, variant, size, ...props }: ButtonProps): import("react").JSX.Element;
package/dist/button.js ADDED
@@ -0,0 +1,9 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ /** Apply the same presentation to an anchor or an application router link. */
3
+ export function buttonClassName({ variant = "primary", size = "md", className } = {}) {
4
+ return ["bnh-button", `bnh-button--${variant}`, `bnh-button--${size}`, className].filter(Boolean).join(" ");
5
+ }
6
+ /** A native button. Set type="button" when it must not submit a form. */
7
+ export function Button({ className, variant = "primary", size = "md", ...props }) {
8
+ return (_jsx("button", { className: buttonClassName({ variant, size, className }), ...props }));
9
+ }
@@ -0,0 +1,16 @@
1
+ import type { ComponentPropsWithRef } from "react";
2
+ export interface ColorOption {
3
+ value: string;
4
+ label: string;
5
+ disabled?: boolean;
6
+ }
7
+ export interface ColorPickerProps extends Omit<ComponentPropsWithRef<"div">, "onChange"> {
8
+ value: string | null;
9
+ onChange: (value: string | null) => void;
10
+ colors: readonly ColorOption[];
11
+ disabled?: boolean;
12
+ allowNone?: boolean;
13
+ noneLabel?: string;
14
+ }
15
+ /** Palette, persistence, and the meaning of each color belong to the application. */
16
+ export declare function ColorPicker({ value, onChange, colors, disabled, allowNone, noneLabel, className, "aria-label": ariaLabel, ...props }: ColorPickerProps): import("react").JSX.Element;
@@ -0,0 +1,7 @@
1
+ "use client";
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { Ban } from "lucide-react";
4
+ /** Palette, persistence, and the meaning of each color belong to the application. */
5
+ export function ColorPicker({ value, onChange, colors, disabled, allowNone = true, noneLabel = "None", className, "aria-label": ariaLabel = "Color", ...props }) {
6
+ return (_jsxs("div", { ...props, role: "group", "aria-label": ariaLabel, className: ["bnh-color-picker", className].filter(Boolean).join(" "), children: [allowNone && _jsx("button", { type: "button", className: "bnh-color-picker-none", disabled: disabled, title: noneLabel, "aria-label": noneLabel, "aria-pressed": value === null, onClick: () => onChange(null), children: _jsx(Ban, { "aria-hidden": "true", size: 18 }) }), colors.map((color) => (_jsx("button", { type: "button", disabled: disabled || color.disabled, title: color.label, "aria-label": color.label, "aria-pressed": value === color.value, style: { backgroundColor: color.value, color: color.value }, onClick: () => onChange(color.value) }, color.value)))] }));
7
+ }
@@ -0,0 +1,17 @@
1
+ import { type ReactNode } from "react";
2
+ export interface ConfirmDialogProps {
3
+ open: boolean;
4
+ title: string;
5
+ message: string;
6
+ confirmLabel?: string;
7
+ confirmVariant?: "primary" | "danger";
8
+ onConfirm: () => void;
9
+ onCancel: () => void;
10
+ loading?: boolean;
11
+ typeToConfirm?: string;
12
+ /** Additional content such as a password field or verification notice. */
13
+ children?: ReactNode;
14
+ /** App-owned prerequisites, combined with loading and typed confirmation. */
15
+ confirmDisabled?: boolean;
16
+ }
17
+ export declare function ConfirmDialog(props: ConfirmDialogProps): import("react").JSX.Element | null;
@@ -0,0 +1,16 @@
1
+ "use client";
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { useState } from "react";
4
+ import { Button } from "./button.js";
5
+ import { Input } from "./input.js";
6
+ import { Modal } from "./modal.js";
7
+ export function ConfirmDialog(props) {
8
+ // Unmounting the form resets the typed phrase each time the dialog closes.
9
+ return props.open ? _jsx(Confirmation, { ...props }, props.typeToConfirm) : null;
10
+ }
11
+ function Confirmation({ title, message, confirmLabel = "Confirm", confirmVariant = "primary", onConfirm, onCancel, loading = false, typeToConfirm, children, confirmDisabled = false }) {
12
+ const [value, setValue] = useState("");
13
+ const disabled = loading || confirmDisabled || (typeToConfirm !== undefined && value !== typeToConfirm);
14
+ return (_jsxs(Modal, { open: true, onOpenChange: (next) => { if (!next)
15
+ onCancel(); }, title: title, persistent: loading, width: 448, zIndex: 300, footer: _jsxs("div", { className: "bnh-confirm-actions", children: [_jsx(Button, { type: "button", variant: "secondary", onClick: onCancel, disabled: loading, children: "Cancel" }), _jsx(Button, { type: "button", variant: confirmVariant, onClick: onConfirm, disabled: disabled, children: loading ? "Loading..." : confirmLabel })] }), children: [_jsx("p", { className: "bnh-confirm-message", children: message }), children, typeToConfirm !== undefined && _jsx(Input, { wrapperClassName: "bnh-confirm-input", label: `Type ${typeToConfirm} to confirm`, value: value, onChange: (event) => setValue(event.target.value), autoFocus: true })] }));
16
+ }
@@ -0,0 +1,24 @@
1
+ import type { ComponentPropsWithRef, Key, ReactNode } from "react";
2
+ export interface DataTableColumn<T> {
3
+ key: string;
4
+ header: ReactNode;
5
+ /** Runs on the server when the table is rendered by a Server Component. */
6
+ render: (row: T) => ReactNode;
7
+ }
8
+ export interface DataTableProps<T> extends Omit<ComponentPropsWithRef<"div">, "children"> {
9
+ columns: readonly DataTableColumn<T>[];
10
+ data: readonly T[];
11
+ loading?: boolean;
12
+ loadingRows?: number;
13
+ emptyMessage?: ReactNode;
14
+ /** Prefer a persistent ID when rows can be inserted, removed, or reordered. */
15
+ getRowKey?: (row: T, index: number) => Key;
16
+ caption?: ReactNode;
17
+ tableClassName?: string;
18
+ /** Requires a Client Component. Use links or buttons in cells for specific actions. */
19
+ onRowClick?: (row: T) => void;
20
+ /** Prefetch on pointer entry or focus within a row. Requires a Client Component. */
21
+ onRowIntent?: (row: T) => void;
22
+ }
23
+ /** A native table with no client boundary, hooks, or event handlers for static rows. */
24
+ export declare function DataTable<T>({ columns, data, loading, loadingRows, emptyMessage, getRowKey, caption, tableClassName, onRowClick, onRowIntent, className, ...props }: DataTableProps<T>): import("react").JSX.Element;
@@ -0,0 +1,28 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Skeleton } from "./skeleton.js";
3
+ /** A native table with no client boundary, hooks, or event handlers for static rows. */
4
+ export function DataTable({ columns, data, loading = false, loadingRows = 5, emptyMessage = "No data found.", getRowKey, caption, tableClassName, onRowClick, onRowIntent, className, ...props }) {
5
+ return (_jsx("div", { ...props, className: ["bnh-data-table", className].filter(Boolean).join(" "), children: _jsxs("table", { className: ["bnh-data-table__table", tableClassName].filter(Boolean).join(" "), "aria-busy": loading || undefined, children: [caption != null && _jsx("caption", { className: "bnh-data-table__caption", children: caption }), _jsx("thead", { children: _jsx("tr", { children: columns.map((column) => _jsx("th", { scope: "col", children: column.header }, column.key)) }) }), _jsx("tbody", { children: loading
6
+ ? Array.from({ length: Math.max(0, loadingRows) }, (_, index) => (_jsx("tr", { children: columns.map((column) => (_jsx("td", { children: _jsx(Skeleton, { className: "bnh-data-table__skeleton" }) }, column.key))) }, index)))
7
+ : data.length === 0
8
+ ? _jsx("tr", { children: _jsx("td", { colSpan: columns.length, className: "bnh-data-table__empty", children: emptyMessage }) })
9
+ : data.map((row, index) => (_jsx("tr", { ...(onRowIntent ? {
10
+ onPointerEnter: () => onRowIntent(row),
11
+ onFocus: () => onRowIntent(row),
12
+ } : {}), ...(onRowClick ? {
13
+ className: "bnh-data-table__row--interactive",
14
+ tabIndex: 0,
15
+ onClick: (event) => {
16
+ const target = event.target;
17
+ if (target.closest("a, button, input, select, textarea, summary, [role='button'], [role='link'], [contenteditable]:not([contenteditable='false'])"))
18
+ return;
19
+ onRowClick(row);
20
+ },
21
+ onKeyDown: (event) => {
22
+ if (event.target === event.currentTarget && (event.key === "Enter" || event.key === " ")) {
23
+ event.preventDefault();
24
+ onRowClick(row);
25
+ }
26
+ },
27
+ } : {}), children: columns.map((column) => _jsx("td", { children: column.render(row) }, column.key)) }, getRowKey ? getRowKey(row, index) : index))) })] }) }));
28
+ }
@@ -0,0 +1,12 @@
1
+ import { type ButtonHTMLAttributes, type ReactNode } from "react";
2
+ import { type PillProps } from "./pill.js";
3
+ export interface ExpandablePillProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange">, Pick<PillProps, "tint" | "background" | "borderColor" | "height"> {
4
+ panel: ReactNode;
5
+ open?: boolean;
6
+ defaultOpen?: boolean;
7
+ onOpenChange?: (open: boolean) => void;
8
+ panelGap?: number;
9
+ panelMaxWidth?: number | string;
10
+ panelAlign?: "end" | "center";
11
+ }
12
+ export declare function ExpandablePill({ tint, background, borderColor, height, panel, open, defaultOpen, onOpenChange, panelGap, panelMaxWidth, panelAlign, style, className, children, onClick, onKeyDown, type, ...props }: ExpandablePillProps): import("react").JSX.Element;
@@ -0,0 +1,47 @@
1
+ "use client";
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { useId, useRef, useState } from "react";
4
+ import { PILL_HEIGHT } from "./pill.js";
5
+ export function ExpandablePill({ tint, background, borderColor, height = PILL_HEIGHT, panel, open, defaultOpen = false, onOpenChange, panelGap = 6, panelMaxWidth = "calc(100vw - 32px)", panelAlign = "end", style, className, children, onClick, onKeyDown, type = "button", ...props }) {
6
+ const [internalOpen, setInternalOpen] = useState(defaultOpen);
7
+ const triggerRef = useRef(null);
8
+ const panelId = useId();
9
+ const isOpen = open ?? internalOpen;
10
+ const centered = panelAlign === "center";
11
+ function changeOpen(value) {
12
+ if (open === undefined)
13
+ setInternalOpen(value);
14
+ onOpenChange?.(value);
15
+ }
16
+ return (_jsxs("span", { className: "bnh-expandable-pill", style: { position: centered ? "static" : "relative" }, onKeyDown: (event) => {
17
+ // Portaled widgets remain in this React subtree, but own their keyboard
18
+ // interaction. A nested disclosure can also consume Escape first.
19
+ if (event.defaultPrevented || event.key !== "Escape" || !isOpen
20
+ || !event.currentTarget.contains(event.target))
21
+ return;
22
+ event.preventDefault();
23
+ event.stopPropagation();
24
+ changeOpen(false);
25
+ triggerRef.current?.focus();
26
+ }, children: [_jsx("button", { ...props, ref: triggerRef, type: type, "aria-expanded": isOpen, "aria-controls": panelId, className: ["bnh-pill", "bnh-expandable-pill-trigger", className].filter(Boolean).join(" "), style: {
27
+ height,
28
+ whiteSpace: "nowrap",
29
+ background: background ?? (tint ? `color-mix(in oklch, ${tint} 8%, transparent)` : "transparent"),
30
+ border: `1px solid ${borderColor ?? (tint ? `color-mix(in oklch, ${tint} 30%, transparent)` : "var(--bnh-border)")}`,
31
+ ...style,
32
+ }, onClick: (event) => {
33
+ onClick?.(event);
34
+ if (!event.defaultPrevented)
35
+ changeOpen(!isOpen);
36
+ }, onKeyDown: onKeyDown, children: children }), _jsx("div", { id: panelId, className: "bnh-expandable-pill-panel", inert: !isOpen, "aria-hidden": !isOpen, style: {
37
+ top: `calc(100% + ${panelGap}px)`,
38
+ ...(centered
39
+ ? { left: 16, right: 16, display: "flex", justifyContent: "center" }
40
+ : { right: 0, maxWidth: panelMaxWidth }),
41
+ opacity: isOpen ? 1 : 0,
42
+ pointerEvents: isOpen ? "auto" : "none",
43
+ transform: isOpen ? "translateY(0) scale(1)" : "translateY(-4px) scale(.98)",
44
+ transformOrigin: centered ? "top center" : "top right",
45
+ visibility: isOpen ? "visible" : "hidden",
46
+ }, children: panel })] }));
47
+ }