@handamade/psi-react 0.7.1 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Kurkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @handamade/psi-react
 
-15 React 19 components consuming @handamade/psi-tokens. Zero runtime dependencies, CSS Modules, full TypeScript support.
+18 React 19 components consuming @handamade/psi-tokens. Zero runtime dependencies, CSS Modules, full TypeScript support.
 
 ## Installation
 

package/dist/Menu/Menu.d.ts

@@ -0,0 +1,57 @@
+import type { ReactElement, ReactNode, Ref } from "react";
+export type MenuPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+export interface MenuContextValue {
+    close: (reason: "item-select") => void;
+}
+export declare const MenuContext: import("react").Context<MenuContextValue>;
+export interface MenuProps {
+    /** Controlled open state; syncs to showPopover()/hidePopover(). */
+    open: boolean;
+    /**
+     * Called when a dismissal is *requested*; the consumer flips `open`.
+     *
+     * Menu never closes itself on `"esc"` or `"item-select"` — the popover stays
+     * open until `open` becomes false (D50). `"outside"` is the one exception:
+     * light dismiss is performed by the browser before it tells us, so by the
+     * time that reason is reported the popover is already closed. Flipping
+     * `open` to false is still required, to keep React's state in step.
+     */
+    onClose: (reason: "esc" | "outside" | "item-select") => void;
+    /**
+     * The trigger element. Must be a single React element that spreads unknown
+     * props onto a focusable node (a Psi `Button`, say): Menu clones it to add
+     * `aria-haspopup="menu"` and `aria-expanded`, so assistive tech associates
+     * the menu with the control users actually focus.
+     */
+    trigger: ReactElement<Record<string, unknown>>;
+    /** Placement relative to the trigger. @default "bottom-start" */
+    placement?: MenuPlacement;
+    /** Accessible name for the menu when there is no visible label. */
+    "aria-label"?: string;
+    children: ReactNode;
+    className?: string;
+    /** Forwarded ref to the popover element. */
+    ref?: Ref<HTMLDivElement>;
+}
+/** Action menu on the native Popover API top layer: the top layer and light
+ * dismiss come from the platform; Esc, roving keyboard, placement and
+ * dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50).
+ *
+ * Controlled-only means Menu does not change its own visibility. Esc and
+ * item-select *report* a dismissal via onClose(reason) and leave the popover
+ * open; only the consumer flipping `open` to false actually closes it. Esc
+ * calls preventDefault() to suppress the platform's own popover dismissal,
+ * which is what makes that possible.
+ *
+ * Light dismiss (outside click) is the one asymmetry, and it is forced by the
+ * platform: the browser hides the popover itself and the hide-side
+ * `beforetoggle` is not cancelable, so the popover is already closed by the
+ * time the resulting `toggle` lets us report onClose("outside"). The consumer
+ * must still flip `open` to false so React's state matches the DOM.
+ *
+ * `toggle` therefore reports only that one reason. A close driven by the
+ * consumer (`open` true -> false) runs through the sync effect's own
+ * hidePopover(), which raises a `toggle` too — that one is suppressed, because
+ * a programmatic close is not a dismissal and must not call onClose. */
+export declare function Menu({ open, onClose, trigger, placement, children, className, ref, ...rest }: MenuProps): import("react").JSX.Element;
+//# sourceMappingURL=Menu.d.ts.map

package/dist/Menu/Menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Menu.d.ts","sourceRoot":"","sources":["../../src/Menu/Menu.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAK1D,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;AAEpF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;CACxC;AAED,eAAO,MAAM,WAAW,2CAAuD,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,aAAa,KAAK,IAAI,CAAC;IAC7D;;;;;OAKG;IACH,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,iEAAiE;IACjE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;;;wEAmBwE;AACxE,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,OAAO,EACP,OAAO,EACP,SAA0B,EAC1B,QAAQ,EACR,SAAS,EACT,GAAG,EACH,GAAG,IAAI,EACR,EAAE,SAAS,+BAyGX"}

package/dist/Menu/MenuItem.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+export interface MenuItemProps {
+    children: ReactNode;
+    /** Fires on activation; Menu then reports the dismissal via onClose("item-select") (D50). */
+    onSelect: () => void;
+    /** danger is for destructive actions only (house rule). @default "neutral" */
+    variant?: "neutral" | "danger";
+    disabled?: boolean;
+}
+/** One action in a Menu. Renders a real <button> so activation, Enter and
+ * Space come from the platform; the roving tabindex is applied by Menu's
+ * keyboard hook, which finds items via [data-psi-menu-item] (D53). */
+export declare function MenuItem({ children, onSelect, variant, disabled }: MenuItemProps): import("react").JSX.Element;
+//# sourceMappingURL=MenuItem.d.ts.map

package/dist/Menu/MenuItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MenuItem.d.ts","sourceRoot":"","sources":["../../src/Menu/MenuItem.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,6FAA6F;IAC7F,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;sEAEsE;AACtE,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAmB,EAAE,QAAgB,EAAE,EAAE,aAAa,+BAqBpG"}

package/dist/Menu/MenuSeparator.d.ts

@@ -0,0 +1,3 @@
+/** Hairline rule between Menu item groups. No props by design (D53). */
+export declare function MenuSeparator(): import("react").JSX.Element;
+//# sourceMappingURL=MenuSeparator.d.ts.map

package/dist/Menu/MenuSeparator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MenuSeparator.d.ts","sourceRoot":"","sources":["../../src/Menu/MenuSeparator.tsx"],"names":[],"mappings":"AAEA,wEAAwE;AACxE,wBAAgB,aAAa,gCAE5B"}

package/dist/Menu/useMenuKeyboard.d.ts

@@ -0,0 +1,15 @@
+import type { KeyboardEvent, RefObject } from "react";
+interface Options {
+    popoverRef: RefObject<HTMLDivElement | null>;
+    triggerRef: RefObject<HTMLDivElement | null>;
+    open: boolean;
+    onEsc: () => void;
+}
+/** Roving-tabindex keyboard navigation for Menu (D53): Up/Down with wrap,
+ * Home/End, character typeahead, Esc, and focus return on close. Disabled
+ * items are skipped everywhere. Psi's only keyboard-navigation JS — a
+ * deliberate departure from D52, which refused role="toolbar" precisely to
+ * avoid it. */
+export declare function useMenuKeyboard({ popoverRef, triggerRef, open, onEsc }: Options): (event: KeyboardEvent<HTMLDivElement>) => void;
+export {};
+//# sourceMappingURL=useMenuKeyboard.d.ts.map

package/dist/Menu/useMenuKeyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMenuKeyboard.d.ts","sourceRoot":"","sources":["../../src/Menu/useMenuKeyboard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKtD,UAAU,OAAO;IACf,UAAU,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7C,UAAU,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7C,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;eAIe;AACf,wBAAgB,eAAe,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,WAsDpE,aAAa,CAAC,cAAc,CAAC,UAoExC"}

package/dist/Menu/useMenuPlacement.d.ts

@@ -0,0 +1,18 @@
+import type { RefObject } from "react";
+import type { MenuPlacement } from "./Menu.js";
+interface Options {
+    popoverRef: RefObject<HTMLDivElement | null>;
+    triggerRef: RefObject<HTMLDivElement | null>;
+    open: boolean;
+    placement: MenuPlacement;
+    anchorName: string;
+}
+/** Placement for Menu (D53). Above the anchor floor this hook only declares
+ * anchor-name / position-anchor and lets CSS position the popover. Below it,
+ * a top-layer element's containing block is the viewport — there is no
+ * declarative way to place it near its trigger — so this sets `inset` from
+ * the trigger rect and keeps it current. That branch is dead code above the
+ * anchor floor and is deletable outright once the floor rises. */
+export declare function useMenuPlacement({ popoverRef, triggerRef, open, placement, anchorName }: Options): void;
+export {};
+//# sourceMappingURL=useMenuPlacement.d.ts.map

package/dist/Menu/useMenuPlacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMenuPlacement.d.ts","sourceRoot":"","sources":["../../src/Menu/useMenuPlacement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAQ/C,UAAU,OAAO;IACf,UAAU,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7C,UAAU,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7C,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;kEAKkE;AAClE,wBAAgB,gBAAgB,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,OAAO,QA2ChG"}

package/dist/a11y-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"a11y-meta.d.ts","sourceRoot":"","sources":["../src/a11y-meta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CA0E9C,CAAC"}
+{"version":3,"file":"a11y-meta.d.ts","sourceRoot":"","sources":["../src/a11y-meta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CA8F9C,CAAC"}

package/dist/index.d.ts

@@ -28,5 +28,10 @@ export { Tooltip } from "./Tooltip/Tooltip.js";
 export type { TooltipProps } from "./Tooltip/Tooltip.js";
 export { Toolbar } from "./Toolbar/Toolbar.js";
 export type { ToolbarProps } from "./Toolbar/Toolbar.js";
+export { Menu, MenuContext } from "./Menu/Menu.js";
+export type { MenuProps, MenuPlacement, MenuContextValue } from "./Menu/Menu.js";
+export { MenuItem } from "./Menu/MenuItem.js";
+export type { MenuItemProps } from "./Menu/MenuItem.js";
+export { MenuSeparator } from "./Menu/MenuSeparator.js";
 export { IconPlus, IconMinus, IconClose, IconCheck, IconChevronDown, IconChevronRight, IconSearch, IconSettings, IconUser, IconEdit, IconTrash, IconCopy, IconExternalLink, IconEye, IconEyeOff, IconLoader, IconArrowDown, IconArrowUpRight, IconLinkedIn, IconGitHub, IconX, IconInstagram, } from "./icons/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,UAAU,EACV,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,KAAK,EACL,aAAa,GACd,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,UAAU,EACV,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,KAAK,EACL,aAAa,GACd,MAAM,kBAAkB,CAAC"}