@molecule/app-sidebar-layout-solid 0.0.1-stage → 1.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/README.md +199 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,206 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-21T12:47:19.311Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-sidebar-layout-solid
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Solid vertical sidebar app shell layout.
|
|
12
|
+
|
|
13
|
+
Exports `SidebarLayout` plus the `SidebarLayoutProps` and `SidebarNavItem`
|
|
14
|
+
types — fixed-width left sidebar with brand link, vertical nav links, and
|
|
15
|
+
bottom user-menu / theme-toggle slots; the main area on the right scrolls and
|
|
16
|
+
renders the routed view.
|
|
17
|
+
|
|
18
|
+
It is the Solid counterpart of `@molecule/app-sidebar-layout-react`: same
|
|
19
|
+
props and the same DOM for the same input. React renders React Router's
|
|
20
|
+
`<Outlet />` in the main area; here the routed view goes in `children`.
|
|
21
|
+
|
|
22
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
23
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
24
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
import { SidebarLayout } from '@molecule/app-sidebar-layout-solid'
|
|
30
|
+
import type { SidebarNavItem } from '@molecule/app-sidebar-layout-solid'
|
|
31
|
+
|
|
32
|
+
const NAV: SidebarNavItem[] = [
|
|
33
|
+
{ key: 'dashboard', to: '/dashboard', icon: 'dashboard', label: 'Dashboard' },
|
|
34
|
+
{ key: 'projects', to: '/projects', icon: 'folder', label: 'Projects' },
|
|
35
|
+
{ key: 'settings', to: '/settings', icon: 'settings', label: 'Settings' },
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
export function AppShell() {
|
|
39
|
+
return (
|
|
40
|
+
<SidebarLayout appName="Acme App" navItems={NAV}>
|
|
41
|
+
<RouterView />
|
|
42
|
+
</SidebarLayout>
|
|
43
|
+
)
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Type
|
|
48
|
+
|
|
49
|
+
`feature`
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install @molecule/app-sidebar-layout-solid @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## API
|
|
58
|
+
|
|
59
|
+
### Interfaces
|
|
60
|
+
|
|
61
|
+
#### `SidebarNavItem`
|
|
62
|
+
|
|
63
|
+
Describes a single item in the sidebar's vertical navigation list.
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
interface SidebarNavItem {
|
|
67
|
+
/** Route path the link goes to. */
|
|
68
|
+
to: string
|
|
69
|
+
/** Stable key — used for list keys and i18n key suffix. */
|
|
70
|
+
key: string
|
|
71
|
+
/** Material symbol icon name. */
|
|
72
|
+
icon?: string
|
|
73
|
+
/** Visible label. Apps that route this through `t(...)` should pass the resolved string. */
|
|
74
|
+
label: string
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
#### `SidebarLayoutProps`
|
|
4
79
|
|
|
80
|
+
Props accepted by the {@link SidebarLayout} component.
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
interface SidebarLayoutProps {
|
|
84
|
+
/** Brand text shown at the top of the sidebar (typically the app name). */
|
|
85
|
+
appName: string
|
|
86
|
+
/** Path the brand link navigates to. Defaults to `'/'`. */
|
|
87
|
+
logoTo?: string
|
|
88
|
+
/** Vertical nav items rendered in the sidebar. */
|
|
89
|
+
navItems: ReadonlyArray<SidebarNavItem>
|
|
90
|
+
/** Slot rendered at the bottom of the sidebar (typically a user menu). */
|
|
91
|
+
userMenu?: JSX.Element
|
|
92
|
+
/** Optional slot rendered next to the user menu (typically a theme toggle). */
|
|
93
|
+
themeToggle?: JSX.Element
|
|
94
|
+
/**
|
|
95
|
+
* Aria-label for the primary `<nav>`. Overrides the translated default
|
|
96
|
+
* (`sidebarLayout.aria.primaryNavigation`, English `'Primary navigation'`);
|
|
97
|
+
* prop > `t()` > default.
|
|
98
|
+
*/
|
|
99
|
+
navAriaLabel?: string
|
|
100
|
+
/**
|
|
101
|
+
* Sidebar width — a stack-agnostic preset (`'sm'` | `'md'` | `'lg'`) or an
|
|
102
|
+
* exact pixel `number`. Applied via inline style. Defaults to `'md'` (240px).
|
|
103
|
+
*/
|
|
104
|
+
sidebarWidth?: SidebarWidth
|
|
105
|
+
/**
|
|
106
|
+
* Legacy sidebar-width prop retained only for backward compatibility: a
|
|
107
|
+
* `w-<n>` value is PARSED to a pixel width and applied via inline style
|
|
108
|
+
* (never re-emitted as a class). `sidebarWidth` takes precedence.
|
|
109
|
+
*
|
|
110
|
+
* @deprecated Use {@link SidebarLayoutProps.sidebarWidth} instead.
|
|
111
|
+
*/
|
|
112
|
+
sidebarWidthClass?: string
|
|
113
|
+
/** Extra classes on the outer wrapper. */
|
|
114
|
+
className?: string
|
|
115
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
116
|
+
dataMolId?: string
|
|
117
|
+
/**
|
|
118
|
+
* The routed page body. React renders React Router's `<Outlet />` in the
|
|
119
|
+
* `<main>`; pass the routed view or any content here.
|
|
120
|
+
*/
|
|
121
|
+
children?: JSX.Element
|
|
122
|
+
}
|
|
5
123
|
```
|
|
6
|
-
|
|
124
|
+
|
|
125
|
+
### Types
|
|
126
|
+
|
|
127
|
+
#### `SidebarWidth`
|
|
128
|
+
|
|
129
|
+
Semantic sidebar width. Mapped to a fixed pixel width internally and applied
|
|
130
|
+
via inline style (a width is one of the "specific values" a styling-agnostic
|
|
131
|
+
ClassMap cannot express as a swappable token) so the sidebar renders the same
|
|
132
|
+
regardless of which ClassMap bond is active — no Tailwind width utility leaks
|
|
133
|
+
into consumer code.
|
|
134
|
+
|
|
135
|
+
- `sm` → 208px, `md` → 240px (default), `lg` → 256px.
|
|
136
|
+
- Pass a raw `number` for an exact pixel width.
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
type SidebarWidth = 'sm' | 'md' | 'lg' | number
|
|
7
140
|
```
|
|
8
141
|
|
|
9
|
-
|
|
142
|
+
### Functions
|
|
143
|
+
|
|
144
|
+
#### `SidebarLayout(props)`
|
|
145
|
+
|
|
146
|
+
Vertical sidebar shell with brand + vertical nav + bottom user-menu slot.
|
|
147
|
+
|
|
148
|
+
This is the Solid counterpart of `@molecule/app-sidebar-layout-react`: the
|
|
149
|
+
same props (React names), the same ClassMap tokens, and the same DOM for the
|
|
150
|
+
same input. The routed page body goes in `children`, where React renders
|
|
151
|
+
React Router's `<Outlet />`. The sidebar WIDTH is the one value a
|
|
152
|
+
styling-agnostic ClassMap can't express, so it is applied via inline style
|
|
153
|
+
from `sidebarWidth`; active-nav highlighting picks the longest prefix-match
|
|
154
|
+
of the current path, and same-path links get a `#top` fragment appended.
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
function SidebarLayout(props: SidebarLayoutProps): JSX.Element
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
- `props` — Component props (see {@link SidebarLayoutProps}).
|
|
161
|
+
|
|
162
|
+
**Returns:** The rendered sidebar layout.
|
|
163
|
+
|
|
164
|
+
## Injection Notes
|
|
165
|
+
|
|
166
|
+
### Requirements
|
|
167
|
+
|
|
168
|
+
Peer dependencies:
|
|
169
|
+
|
|
170
|
+
- `@molecule/app-solid` ^3.6.0
|
|
171
|
+
- `@molecule/app-ui` ^1.3.11
|
|
172
|
+
- `@molecule/app-ui-solid` ^1.1.0
|
|
173
|
+
- `solid-js` ^1.8.0
|
|
174
|
+
|
|
175
|
+
### Runtime Dependencies
|
|
176
|
+
|
|
177
|
+
- `@molecule/app-solid`
|
|
178
|
+
- `@molecule/app-ui`
|
|
179
|
+
- `@molecule/app-ui-solid`
|
|
180
|
+
- `solid-js`
|
|
181
|
+
|
|
182
|
+
- Router required: reads the current location and renders router links, so
|
|
183
|
+
it must be mounted inside the molecule router provider (the app shell
|
|
184
|
+
does that at startup).
|
|
185
|
+
- Fully ClassMap-driven: every layout/surface/border/text/state class is
|
|
186
|
+
resolved through `getClassMap()` (`cm.pageShell`, `cm.page`, `cm.surface`,
|
|
187
|
+
`cm.borderR`, …), so swapping the ClassMap bond restyles the whole shell.
|
|
188
|
+
The sidebar WIDTH is applied via inline style from `sidebarWidth`
|
|
189
|
+
(`'sm'`|`'md'`|`'lg'`|pixel `number`); the old `sidebarWidthClass` prop is
|
|
190
|
+
`@deprecated` — parsed to pixels, never re-emitted as a class.
|
|
191
|
+
- `icon` values are Material Symbols ligature names rendered with the
|
|
192
|
+
`material-symbols-outlined` font class — the one documented icon-font
|
|
193
|
+
exception. Without the font loaded, the raw icon name shows as text.
|
|
194
|
+
- Active-nav highlighting picks the longest prefix-match of the current
|
|
195
|
+
path; same-path clicks get a `#top` fragment appended.
|
|
196
|
+
- `navAriaLabel` overrides the translated nav region name; without it the
|
|
197
|
+
label comes from `t('sidebarLayout.aria.primaryNavigation')` (English
|
|
198
|
+
default `'Primary navigation'`), so it follows a locale switch through its
|
|
199
|
+
companion locale bond (`@molecule/app-locales-sidebar-layout`). Nav item
|
|
200
|
+
`label`s stay plain caller strings — translate them upstream.
|
|
201
|
+
- Requires a bonded ClassMap. Sibling: `@molecule/app-shell-layout-solid` is
|
|
202
|
+
the top header/footer shell (router-free).
|
|
203
|
+
|
|
204
|
+
## Translations
|
|
10
205
|
|
|
11
|
-
|
|
206
|
+
Translation strings are provided by `@molecule/app-locales-sidebar-layout`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-sidebar-layout-solid",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Vertical sidebar app shell: brand block + vertical NavLinks + user-menu slot, with a router outlet for nested routes",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-sidebar-layout-solid",
|
|
6
6
|
"type": "module",
|
|
@@ -52,9 +52,9 @@
|
|
|
52
52
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
53
53
|
"@molecule/app-i18n": "1.2.2",
|
|
54
54
|
"@molecule/app-icons": "1.0.4",
|
|
55
|
-
"@molecule/app-solid": "3.
|
|
56
|
-
"@molecule/app-ui": "1.
|
|
57
|
-
"@molecule/app-ui-solid": "1.1
|
|
55
|
+
"@molecule/app-solid": "3.9.0",
|
|
56
|
+
"@molecule/app-ui": "1.5.0",
|
|
57
|
+
"@molecule/app-ui-solid": "1.2.1",
|
|
58
58
|
"@types/node": "26.6.5",
|
|
59
59
|
"jsdom": "30.1.3",
|
|
60
60
|
"solid-js": "1.9.17",
|