@lenso/primitives 0.1.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lenso 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,5 @@
1
+ # @lenso/primitives
2
+
3
+ Headless, style-free product primitives. The MVP surface contains the composable Sidebar state and accessibility model.
4
+
5
+ Import `Sidebar` from `@lenso/primitives/sidebar`. Its compound parts support controlled and uncontrolled state, independent left and right panels, nested sidebars, keyboard dismissal, and focus restoration without imposing CSS or an animation runtime. Consumers own composition and visuals; the Lenso registry includes one styled Sidebar Recipe as an editable starting point.
@@ -0,0 +1,111 @@
1
+ import * as React from "react";
2
+ import { Button } from "@base-ui/react/button";
3
+ import { useRender } from "@base-ui/react/use-render";
4
+ export type SidebarSide = "left" | "right";
5
+ export type SidebarDirection = "ltr" | "rtl";
6
+ export interface SidebarState {
7
+ open: boolean;
8
+ }
9
+ export interface SidebarActions {
10
+ setOpen: (open: boolean) => void;
11
+ toggle: () => void;
12
+ }
13
+ export interface SidebarMeta {
14
+ dir: SidebarDirection;
15
+ panelId: string;
16
+ rootId: string;
17
+ side: SidebarSide;
18
+ triggerRef: React.RefObject<HTMLElement | null>;
19
+ }
20
+ type SidebarRenderProps<ElementType extends React.ElementType, State = {}> = Omit<useRender.ComponentProps<ElementType, State>, "ref"> & {
21
+ ref?: React.Ref<HTMLElement>;
22
+ };
23
+ export interface SidebarGroupProps extends SidebarRenderProps<"div"> {
24
+ }
25
+ export declare function SidebarGroup({ children, ref, render, ...props }: SidebarGroupProps): React.JSX.Element;
26
+ export interface SidebarProviderProps {
27
+ actions: SidebarActions;
28
+ children?: React.ReactNode;
29
+ meta: SidebarMeta;
30
+ state: SidebarState;
31
+ }
32
+ export declare function SidebarProvider({ actions, children, meta, state }: SidebarProviderProps): React.JSX.Element;
33
+ export type SidebarRootState = {
34
+ dir: SidebarDirection;
35
+ open: boolean;
36
+ side: SidebarSide;
37
+ };
38
+ export interface SidebarRootProps extends Omit<SidebarRenderProps<"div", SidebarRootState>, "defaultValue" | "dir"> {
39
+ defaultOpen?: boolean;
40
+ dir?: SidebarDirection;
41
+ onOpenChange?: (open: boolean) => void;
42
+ open?: boolean;
43
+ side?: SidebarSide;
44
+ }
45
+ export declare function SidebarRoot({ defaultOpen, dir, id, onOpenChange, open, ref, render, side, ...props }: SidebarRootProps): React.JSX.Element;
46
+ export interface SidebarTriggerProps extends Omit<Button.Props, "ref"> {
47
+ ref?: React.Ref<HTMLElement>;
48
+ targetId?: string;
49
+ }
50
+ export declare function SidebarTrigger({ onClick, ref, targetId, ...props }: SidebarTriggerProps): React.JSX.Element;
51
+ export type SidebarPanelState = {
52
+ open: boolean;
53
+ side: SidebarSide;
54
+ };
55
+ export interface SidebarPanelProps extends SidebarRenderProps<"aside", SidebarPanelState> {
56
+ }
57
+ export declare function SidebarPanel({ onKeyDown, ref, render, ...props }: SidebarPanelProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
58
+ export interface SidebarRailProps extends Omit<Button.Props, "ref"> {
59
+ closeLabel?: string;
60
+ openLabel?: string;
61
+ ref?: React.Ref<HTMLElement>;
62
+ targetId?: string;
63
+ }
64
+ export declare function SidebarRail({ "aria-label": ariaLabel, closeLabel, onClick, openLabel, ref, targetId, ...props }: SidebarRailProps): React.JSX.Element;
65
+ export interface SidebarHeaderProps extends SidebarRenderProps<"div"> {
66
+ }
67
+ export declare function SidebarHeader(props: SidebarHeaderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
68
+ export interface SidebarContentProps extends SidebarRenderProps<"div"> {
69
+ }
70
+ export declare function SidebarContent(props: SidebarContentProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
71
+ export interface SidebarFooterProps extends SidebarRenderProps<"div"> {
72
+ }
73
+ export declare function SidebarFooter(props: SidebarFooterProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
74
+ export interface SidebarMenuProps extends SidebarRenderProps<"ul"> {
75
+ }
76
+ export declare function SidebarMenu(props: SidebarMenuProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
77
+ export interface SidebarSubmenuProps extends SidebarRenderProps<"ul"> {
78
+ }
79
+ export declare function SidebarSubmenu(props: SidebarSubmenuProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
80
+ export interface SidebarMenuItemProps extends SidebarRenderProps<"li"> {
81
+ }
82
+ export declare function SidebarMenuItem(props: SidebarMenuItemProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
83
+ export type SidebarItemState = {
84
+ nested: boolean;
85
+ selected: boolean;
86
+ };
87
+ export interface SidebarItemProps extends SidebarRenderProps<"button", SidebarItemState> {
88
+ nested?: boolean;
89
+ selected?: boolean;
90
+ }
91
+ export declare function SidebarItem({ nested, ref, render, selected, ...props }: SidebarItemProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
92
+ export interface SidebarInsetProps extends SidebarRenderProps<"main"> {
93
+ }
94
+ export declare function SidebarInset(props: SidebarInsetProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
95
+ export declare const Sidebar: {
96
+ readonly Content: typeof SidebarContent;
97
+ readonly Footer: typeof SidebarFooter;
98
+ readonly Group: typeof SidebarGroup;
99
+ readonly Header: typeof SidebarHeader;
100
+ readonly Inset: typeof SidebarInset;
101
+ readonly Item: typeof SidebarItem;
102
+ readonly Menu: typeof SidebarMenu;
103
+ readonly MenuItem: typeof SidebarMenuItem;
104
+ readonly Panel: typeof SidebarPanel;
105
+ readonly Provider: typeof SidebarProvider;
106
+ readonly Rail: typeof SidebarRail;
107
+ readonly Root: typeof SidebarRoot;
108
+ readonly Submenu: typeof SidebarSubmenu;
109
+ readonly Trigger: typeof SidebarTrigger;
110
+ };
111
+ export {};
@@ -0,0 +1,302 @@
1
+ "use client";
2
+ import * as React from "react";
3
+ import { Button } from "@base-ui/react/button";
4
+ import { mergeProps } from "@base-ui/react/merge-props";
5
+ import { useRender } from "@base-ui/react/use-render";
6
+ import { jsx } from "react/jsx-runtime";
7
+ //#region src/sidebar/index.tsx
8
+ const SidebarContext = React.createContext(null);
9
+ const SidebarGroupContext = React.createContext(null);
10
+ function useSidebarController(part) {
11
+ const nearest = React.useContext(SidebarContext);
12
+ if (!nearest) throw new Error(`Sidebar.${part} must be used within Sidebar.Root`);
13
+ return nearest;
14
+ }
15
+ const noopSubscribe = () => () => {};
16
+ function useTargetController(targetId) {
17
+ const group = React.useContext(SidebarGroupContext);
18
+ return React.useSyncExternalStore(group?.subscribe ?? noopSubscribe, () => targetId ? group?.get(targetId) ?? null : null, () => null);
19
+ }
20
+ function useControllableOpen({ defaultOpen, onOpenChange, open }) {
21
+ const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
22
+ const controlled = open !== void 0;
23
+ const currentOpen = controlled ? open : uncontrolledOpen;
24
+ return [currentOpen, React.useCallback((nextOpen) => {
25
+ if (!controlled) setUncontrolledOpen(nextOpen);
26
+ if (nextOpen !== currentOpen) onOpenChange?.(nextOpen);
27
+ }, [
28
+ controlled,
29
+ currentOpen,
30
+ onOpenChange
31
+ ])];
32
+ }
33
+ function composeRefs(...refs) {
34
+ return (node) => {
35
+ for (const ref of refs) if (typeof ref === "function") ref(node);
36
+ else if (ref) ref.current = node;
37
+ };
38
+ }
39
+ function SidebarGroup({ children, ref, render, ...props }) {
40
+ const store = React.useRef({
41
+ controllers: /* @__PURE__ */ new Map(),
42
+ listeners: /* @__PURE__ */ new Set()
43
+ });
44
+ const value = React.useMemo(() => ({
45
+ get: (rootId) => store.current.controllers.get(rootId) ?? null,
46
+ register: (controller) => {
47
+ store.current.controllers.set(controller.meta.rootId, controller);
48
+ for (const listener of store.current.listeners) listener();
49
+ return () => {
50
+ if (store.current.controllers.get(controller.meta.rootId) === controller) {
51
+ store.current.controllers.delete(controller.meta.rootId);
52
+ for (const listener of store.current.listeners) listener();
53
+ }
54
+ };
55
+ },
56
+ subscribe: (listener) => {
57
+ store.current.listeners.add(listener);
58
+ return () => store.current.listeners.delete(listener);
59
+ }
60
+ }), []);
61
+ const element = useRender({
62
+ defaultTagName: "div",
63
+ ref,
64
+ render,
65
+ props: {
66
+ ...mergeProps({ children }, props),
67
+ "data-slot": "sidebar-group"
68
+ }
69
+ });
70
+ return /* @__PURE__ */ jsx(SidebarGroupContext.Provider, {
71
+ value,
72
+ children: element
73
+ });
74
+ }
75
+ function SidebarProvider({ actions, children, meta, state }) {
76
+ const group = React.useContext(SidebarGroupContext);
77
+ const controller = React.useMemo(() => ({
78
+ actions,
79
+ meta,
80
+ state
81
+ }), [
82
+ actions,
83
+ meta,
84
+ state
85
+ ]);
86
+ React.useEffect(() => group?.register(controller), [controller, group]);
87
+ return /* @__PURE__ */ jsx(SidebarContext.Provider, {
88
+ value: controller,
89
+ children
90
+ });
91
+ }
92
+ function SidebarRoot({ defaultOpen = true, dir = "ltr", id, onOpenChange, open, ref, render, side = "left", ...props }) {
93
+ const generatedId = React.useId();
94
+ const rootId = id ?? `sidebar-${generatedId.replaceAll(":", "")}`;
95
+ const panelId = `${rootId}-panel`;
96
+ const [currentOpen, setOpen] = useControllableOpen({
97
+ defaultOpen,
98
+ onOpenChange,
99
+ open
100
+ });
101
+ const triggerRef = React.useRef(null);
102
+ const state = React.useMemo(() => ({ open: currentOpen }), [currentOpen]);
103
+ const actions = React.useMemo(() => ({
104
+ setOpen,
105
+ toggle: () => setOpen(!currentOpen)
106
+ }), [currentOpen, setOpen]);
107
+ const meta = React.useMemo(() => ({
108
+ dir,
109
+ panelId,
110
+ rootId,
111
+ side,
112
+ triggerRef
113
+ }), [
114
+ dir,
115
+ panelId,
116
+ rootId,
117
+ side
118
+ ]);
119
+ const renderState = React.useMemo(() => ({
120
+ dir,
121
+ open: currentOpen,
122
+ side
123
+ }), [
124
+ currentOpen,
125
+ dir,
126
+ side
127
+ ]);
128
+ const element = useRender({
129
+ defaultTagName: "div",
130
+ ref,
131
+ render,
132
+ state: renderState,
133
+ stateAttributesMapping: {
134
+ dir: () => null,
135
+ open: (value) => ({ "data-state": value ? "open" : "closed" }),
136
+ side: (value) => ({ "data-side": value })
137
+ },
138
+ props: {
139
+ ...mergeProps({
140
+ dir,
141
+ id: rootId
142
+ }, props),
143
+ "data-slot": "sidebar-root"
144
+ }
145
+ });
146
+ return /* @__PURE__ */ jsx(SidebarProvider, {
147
+ actions,
148
+ meta,
149
+ state,
150
+ children: element
151
+ });
152
+ }
153
+ function SidebarTrigger({ onClick, ref, targetId, ...props }) {
154
+ const nearest = React.useContext(SidebarContext);
155
+ const targeted = useTargetController(targetId);
156
+ const controller = targetId ? targeted : nearest;
157
+ if (!targetId && !controller) throw new Error("Sidebar.Trigger must be used within Sidebar.Root or specify targetId");
158
+ const panelId = controller?.meta.panelId ?? `${targetId}-panel`;
159
+ const open = controller?.state.open ?? false;
160
+ return /* @__PURE__ */ jsx(Button, {
161
+ ...props,
162
+ "aria-controls": panelId,
163
+ "aria-expanded": open,
164
+ "data-side": controller?.meta.side,
165
+ "data-slot": "sidebar-trigger",
166
+ "data-state": open ? "open" : "closed",
167
+ disabled: props.disabled || !controller,
168
+ onClick: (event) => {
169
+ onClick?.(event);
170
+ if (!event.defaultPrevented && !event.baseUIHandlerPrevented) controller?.actions.toggle();
171
+ },
172
+ ref: controller ? composeRefs(controller.meta.triggerRef, ref) : ref
173
+ });
174
+ }
175
+ function SidebarPanel({ onKeyDown, ref, render, ...props }) {
176
+ const controller = useSidebarController("Panel");
177
+ const state = React.useMemo(() => ({
178
+ open: controller.state.open,
179
+ side: controller.meta.side
180
+ }), [controller.meta.side, controller.state.open]);
181
+ return useRender({
182
+ defaultTagName: "aside",
183
+ ref,
184
+ render,
185
+ state,
186
+ stateAttributesMapping: {
187
+ open: (value) => ({ "data-state": value ? "open" : "closed" }),
188
+ side: (value) => ({ "data-side": value })
189
+ },
190
+ props: {
191
+ ...mergeProps({
192
+ "aria-hidden": !controller.state.open,
193
+ hidden: !controller.state.open,
194
+ id: controller.meta.panelId,
195
+ onKeyDown(event) {
196
+ if (event.key === "Escape" && !event.defaultPrevented) {
197
+ event.preventDefault();
198
+ controller.actions.setOpen(false);
199
+ queueMicrotask(() => controller.meta.triggerRef.current?.focus());
200
+ }
201
+ }
202
+ }, {
203
+ ...props,
204
+ onKeyDown
205
+ }),
206
+ "data-slot": "sidebar-panel"
207
+ }
208
+ });
209
+ }
210
+ function SidebarRail({ "aria-label": ariaLabel, closeLabel = "Close sidebar", onClick, openLabel = "Open sidebar", ref, targetId, ...props }) {
211
+ const nearest = React.useContext(SidebarContext);
212
+ const targeted = useTargetController(targetId);
213
+ const controller = targetId ? targeted : nearest;
214
+ if (!targetId && !controller) throw new Error("Sidebar.Rail must be used within Sidebar.Root or specify targetId");
215
+ const panelId = controller?.meta.panelId ?? `${targetId}-panel`;
216
+ const open = controller?.state.open ?? false;
217
+ return /* @__PURE__ */ jsx(Button, {
218
+ ...props,
219
+ "aria-controls": panelId,
220
+ "aria-expanded": open,
221
+ "aria-label": ariaLabel ?? (open ? closeLabel : openLabel),
222
+ "data-side": controller?.meta.side,
223
+ "data-slot": "sidebar-rail",
224
+ "data-state": open ? "open" : "closed",
225
+ disabled: props.disabled || !controller,
226
+ onClick: (event) => {
227
+ onClick?.(event);
228
+ if (!event.defaultPrevented && !event.baseUIHandlerPrevented) controller?.actions.toggle();
229
+ },
230
+ ref
231
+ });
232
+ }
233
+ function useSidebarPart(defaultTagName, slot, { ref, render, ...props }) {
234
+ return useRender({
235
+ defaultTagName,
236
+ ref,
237
+ render,
238
+ props: {
239
+ ...props,
240
+ "data-slot": slot
241
+ }
242
+ });
243
+ }
244
+ function SidebarHeader(props) {
245
+ return useSidebarPart("div", "sidebar-header", props);
246
+ }
247
+ function SidebarContent(props) {
248
+ return useSidebarPart("div", "sidebar-content", props);
249
+ }
250
+ function SidebarFooter(props) {
251
+ return useSidebarPart("div", "sidebar-footer", props);
252
+ }
253
+ function SidebarMenu(props) {
254
+ return useSidebarPart("ul", "sidebar-menu", props);
255
+ }
256
+ function SidebarSubmenu(props) {
257
+ return useSidebarPart("ul", "sidebar-submenu", props);
258
+ }
259
+ function SidebarMenuItem(props) {
260
+ return useSidebarPart("li", "sidebar-menu-item", props);
261
+ }
262
+ function SidebarItem({ nested = false, ref, render, selected = false, ...props }) {
263
+ const state = React.useMemo(() => ({
264
+ nested,
265
+ selected
266
+ }), [nested, selected]);
267
+ return useRender({
268
+ defaultTagName: "button",
269
+ ref,
270
+ render,
271
+ state,
272
+ stateAttributesMapping: {
273
+ nested: (value) => ({ "data-level": value ? "nested" : "root" }),
274
+ selected: (value) => ({ "data-state": value ? "selected" : "default" })
275
+ },
276
+ props: {
277
+ ...mergeProps({ "aria-current": selected ? "page" : void 0 }, props),
278
+ "data-slot": "sidebar-item"
279
+ }
280
+ });
281
+ }
282
+ function SidebarInset(props) {
283
+ return useSidebarPart("main", "sidebar-inset", props);
284
+ }
285
+ const Sidebar = {
286
+ Content: SidebarContent,
287
+ Footer: SidebarFooter,
288
+ Group: SidebarGroup,
289
+ Header: SidebarHeader,
290
+ Inset: SidebarInset,
291
+ Item: SidebarItem,
292
+ Menu: SidebarMenu,
293
+ MenuItem: SidebarMenuItem,
294
+ Panel: SidebarPanel,
295
+ Provider: SidebarProvider,
296
+ Rail: SidebarRail,
297
+ Root: SidebarRoot,
298
+ Submenu: SidebarSubmenu,
299
+ Trigger: SidebarTrigger
300
+ };
301
+ //#endregion
302
+ export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarHeader, SidebarInset, SidebarItem, SidebarMenu, SidebarMenuItem, SidebarPanel, SidebarProvider, SidebarRail, SidebarRoot, SidebarSubmenu, SidebarTrigger };
package/package.json ADDED
@@ -0,0 +1,44 @@
1
+ {
2
+ "name": "@lenso/primitives",
3
+ "version": "0.1.0",
4
+ "description": "Headless product primitives for Lenso UI.",
5
+ "license": "MIT",
6
+ "files": [
7
+ "dist",
8
+ "README.md"
9
+ ],
10
+ "type": "module",
11
+ "exports": {
12
+ "./sidebar": {
13
+ "types": "./dist/sidebar/index.d.ts",
14
+ "import": "./dist/sidebar/index.js"
15
+ }
16
+ },
17
+ "publishConfig": {
18
+ "access": "public"
19
+ },
20
+ "devDependencies": {
21
+ "@base-ui/react": "1.7.0",
22
+ "@stylexjs/stylex": "0.19.0",
23
+ "@stylexjs/unplugin": "0.19.0",
24
+ "@types/react": "19.2.18",
25
+ "@vitest/browser-playwright": "4.1.10",
26
+ "axe-core": "4.13.0",
27
+ "playwright": "1.62.1",
28
+ "react": "19.2.8",
29
+ "react-dom": "19.2.8",
30
+ "tsdown": "0.22.14",
31
+ "typescript": "7.0.2",
32
+ "vitest": "4.1.10",
33
+ "vitest-browser-react": "2.2.0"
34
+ },
35
+ "peerDependencies": {
36
+ "@base-ui/react": ">=1.7.0 <2.0.0",
37
+ "react": ">=19.2.0 <20.0.0"
38
+ },
39
+ "scripts": {
40
+ "build": "tsdown --config tsdown.config.ts && tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --noEmit false --outDir dist",
41
+ "test": "vitest run --config vitest.config.ts",
42
+ "typecheck": "tsc --noEmit"
43
+ }
44
+ }