@molecule/app-sidebar-layout-vue 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 +259 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,266 @@
|
|
|
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.818Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-sidebar-layout-vue
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Vue vertical sidebar app shell layout.
|
|
12
|
+
|
|
13
|
+
Exports `<SidebarLayout>` plus the `SidebarLayoutProps` and
|
|
14
|
+
`SidebarNavItem` types — fixed-width left sidebar with brand link,
|
|
15
|
+
vertical nav links, and bottom user-menu / theme-toggle slots; the main
|
|
16
|
+
area on the right scrolls and renders the routed view.
|
|
17
|
+
|
|
18
|
+
It is the Vue 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 (`<RouterView />`) is the
|
|
21
|
+
default slot.
|
|
22
|
+
|
|
23
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
24
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
25
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
26
|
+
|
|
27
|
+
## Quick Start
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { createApp, defineComponent, h } from 'vue'
|
|
31
|
+
import { RouterView } from 'vue-router'
|
|
32
|
+
import { SidebarLayout } from '@molecule/app-sidebar-layout-vue'
|
|
33
|
+
import type { SidebarNavItem } from '@molecule/app-sidebar-layout-vue'
|
|
34
|
+
|
|
35
|
+
const NAV: SidebarNavItem[] = [
|
|
36
|
+
{ key: 'dashboard', to: '/dashboard', icon: 'dashboard', label: 'Dashboard' },
|
|
37
|
+
{ key: 'projects', to: '/projects', icon: 'folder', label: 'Projects' },
|
|
38
|
+
{ key: 'settings', to: '/settings', icon: 'settings', label: 'Settings' },
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
const AppShell = defineComponent({
|
|
42
|
+
setup() {
|
|
43
|
+
return () =>
|
|
44
|
+
h(
|
|
45
|
+
SidebarLayout,
|
|
46
|
+
{ appName: 'Acme App', navItems: NAV },
|
|
47
|
+
{
|
|
48
|
+
default: () => [h(RouterView)],
|
|
49
|
+
},
|
|
50
|
+
)
|
|
51
|
+
},
|
|
52
|
+
})
|
|
53
|
+
|
|
54
|
+
createApp(AppShell).mount('#app')
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Type
|
|
4
58
|
|
|
59
|
+
`feature`
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm install @molecule/app-sidebar-layout-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
|
|
5
65
|
```
|
|
6
|
-
|
|
66
|
+
|
|
67
|
+
## API
|
|
68
|
+
|
|
69
|
+
### Interfaces
|
|
70
|
+
|
|
71
|
+
#### `SidebarNavItem`
|
|
72
|
+
|
|
73
|
+
Describes a single item in the sidebar's vertical navigation list.
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
interface SidebarNavItem {
|
|
77
|
+
/** Route path the link goes to. */
|
|
78
|
+
to: string
|
|
79
|
+
/** Stable key — used for list keys and i18n key suffix. */
|
|
80
|
+
key: string
|
|
81
|
+
/** Material symbol icon name. */
|
|
82
|
+
icon?: string
|
|
83
|
+
/** Visible label. Apps that route this through `t(...)` should pass the resolved string. */
|
|
84
|
+
label: string
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
#### `SidebarLayoutProps`
|
|
89
|
+
|
|
90
|
+
Props accepted by the {@link SidebarLayout} component.
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
interface SidebarLayoutProps {
|
|
94
|
+
/** Brand text shown at the top of the sidebar (typically the app name). */
|
|
95
|
+
appName: string
|
|
96
|
+
/** Path the brand link navigates to. Defaults to `'/'`. */
|
|
97
|
+
logoTo?: string
|
|
98
|
+
/** Vertical nav items rendered in the sidebar. */
|
|
99
|
+
navItems: ReadonlyArray<SidebarNavItem>
|
|
100
|
+
/**
|
|
101
|
+
* Slot rendered at the bottom of the sidebar (typically a `<UserMenu />`).
|
|
102
|
+
* Passed as a prop or as the same-named slot — both work.
|
|
103
|
+
*/
|
|
104
|
+
userMenu?: VNodeChild
|
|
105
|
+
/**
|
|
106
|
+
* Optional slot rendered next to the user menu (typically a theme toggle).
|
|
107
|
+
* Passed as a prop or as the same-named slot — both work.
|
|
108
|
+
*/
|
|
109
|
+
themeToggle?: VNodeChild
|
|
110
|
+
/**
|
|
111
|
+
* Aria-label for the primary `<nav>`. Overrides the translated default
|
|
112
|
+
* (`sidebarLayout.aria.primaryNavigation`, English `'Primary navigation'`);
|
|
113
|
+
* prop > `t()` > default.
|
|
114
|
+
*/
|
|
115
|
+
navAriaLabel?: string
|
|
116
|
+
/**
|
|
117
|
+
* Sidebar width — a stack-agnostic preset (`'sm'` | `'md'` | `'lg'`) or an
|
|
118
|
+
* exact pixel `number`. Applied via inline style. Defaults to `'md'` (240px).
|
|
119
|
+
*/
|
|
120
|
+
sidebarWidth?: SidebarWidth
|
|
121
|
+
/**
|
|
122
|
+
* Legacy sidebar-width prop retained only for backward compatibility: a
|
|
123
|
+
* `w-<n>` value is PARSED to a pixel width and applied via inline style
|
|
124
|
+
* (never re-emitted as a class). `sidebarWidth` takes precedence.
|
|
125
|
+
*
|
|
126
|
+
* @deprecated Use {@link SidebarLayoutProps.sidebarWidth} instead.
|
|
127
|
+
*/
|
|
128
|
+
sidebarWidthClass?: string
|
|
129
|
+
/** Extra classes on the outer wrapper. */
|
|
130
|
+
className?: string
|
|
131
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
132
|
+
dataMolId?: string
|
|
133
|
+
/**
|
|
134
|
+
* The routed page body — the DEFAULT slot. React renders React Router's
|
|
135
|
+
* `<Outlet />` here; pass the routed view (`<RouterView />`) or any content.
|
|
136
|
+
*/
|
|
137
|
+
children?: VNodeChild
|
|
138
|
+
}
|
|
7
139
|
```
|
|
8
140
|
|
|
9
|
-
|
|
141
|
+
### Types
|
|
142
|
+
|
|
143
|
+
#### `SidebarWidth`
|
|
144
|
+
|
|
145
|
+
Semantic sidebar width. Mapped to a fixed pixel width internally and applied
|
|
146
|
+
via inline style (a width is one of the "specific values" a styling-agnostic
|
|
147
|
+
ClassMap cannot express as a swappable token) so the sidebar renders the same
|
|
148
|
+
regardless of which ClassMap bond is active — no Tailwind width utility leaks
|
|
149
|
+
into consumer code.
|
|
150
|
+
|
|
151
|
+
- `sm` → 208px, `md` → 240px (default), `lg` → 256px.
|
|
152
|
+
- Pass a raw `number` for an exact pixel width.
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
type SidebarWidth = 'sm' | 'md' | 'lg' | number
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Constants
|
|
159
|
+
|
|
160
|
+
#### `SidebarLayout`
|
|
161
|
+
|
|
162
|
+
Vertical sidebar shell with brand + vertical nav + bottom user-menu slot.
|
|
163
|
+
|
|
164
|
+
The page body comes from the default slot, where React renders React
|
|
165
|
+
Router's `<Outlet />`. The sidebar WIDTH is the one value a styling-agnostic
|
|
166
|
+
ClassMap can't express, so it is applied via inline style from
|
|
167
|
+
`sidebarWidth`; active-nav highlighting picks the longest prefix-match of the
|
|
168
|
+
current path, and same-path links get a `#top` fragment appended.
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
const SidebarLayout: DefineComponent<
|
|
172
|
+
ExtractPropTypes<{
|
|
173
|
+
appName: { type: StringConstructor; required: true }
|
|
174
|
+
logoTo: { type: StringConstructor; default: string }
|
|
175
|
+
navItems: { type: PropType<ReadonlyArray<SidebarNavItem>>; required: true }
|
|
176
|
+
userMenu: null
|
|
177
|
+
themeToggle: null
|
|
178
|
+
navAriaLabel: StringConstructor
|
|
179
|
+
sidebarWidth: { type: PropType<string | number> }
|
|
180
|
+
sidebarWidthClass: StringConstructor
|
|
181
|
+
className: StringConstructor
|
|
182
|
+
dataMolId: StringConstructor
|
|
183
|
+
}>,
|
|
184
|
+
() => VNode,
|
|
185
|
+
{},
|
|
186
|
+
{},
|
|
187
|
+
{},
|
|
188
|
+
ComponentOptionsMixin,
|
|
189
|
+
ComponentOptionsMixin,
|
|
190
|
+
{},
|
|
191
|
+
string,
|
|
192
|
+
PublicProps,
|
|
193
|
+
Readonly<
|
|
194
|
+
ExtractPropTypes<{
|
|
195
|
+
appName: { type: StringConstructor; required: true }
|
|
196
|
+
logoTo: { type: StringConstructor; default: string }
|
|
197
|
+
navItems: { type: PropType<ReadonlyArray<SidebarNavItem>>; required: true }
|
|
198
|
+
userMenu: null
|
|
199
|
+
themeToggle: null
|
|
200
|
+
navAriaLabel: StringConstructor
|
|
201
|
+
sidebarWidth: { type: PropType<string | number> }
|
|
202
|
+
sidebarWidthClass: StringConstructor
|
|
203
|
+
className: StringConstructor
|
|
204
|
+
dataMolId: StringConstructor
|
|
205
|
+
}>
|
|
206
|
+
> &
|
|
207
|
+
Readonly<{}>,
|
|
208
|
+
{ logoTo: string },
|
|
209
|
+
{},
|
|
210
|
+
{},
|
|
211
|
+
{},
|
|
212
|
+
string,
|
|
213
|
+
ComponentProvideOptions,
|
|
214
|
+
true,
|
|
215
|
+
{},
|
|
216
|
+
any
|
|
217
|
+
>
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
- `props` — Component props (see {@link SidebarLayoutProps}).
|
|
221
|
+
|
|
222
|
+
**Returns:** The sidebar layout component.
|
|
223
|
+
|
|
224
|
+
## Injection Notes
|
|
225
|
+
|
|
226
|
+
### Requirements
|
|
227
|
+
|
|
228
|
+
Peer dependencies:
|
|
229
|
+
|
|
230
|
+
- `@molecule/app-ui` ^1.3.11
|
|
231
|
+
- `@molecule/app-ui-vue` ^1.1.0
|
|
232
|
+
- `@molecule/app-vue` ^3.6.0
|
|
233
|
+
- `vue` ^3.4.0
|
|
234
|
+
|
|
235
|
+
### Runtime Dependencies
|
|
236
|
+
|
|
237
|
+
- `@molecule/app-ui`
|
|
238
|
+
- `@molecule/app-ui-vue`
|
|
239
|
+
- `@molecule/app-vue`
|
|
240
|
+
- `vue`
|
|
241
|
+
|
|
242
|
+
- Router required: reads the current location and renders router links, so
|
|
243
|
+
it must be mounted inside the molecule router provider (the app shell
|
|
244
|
+
does that at startup).
|
|
245
|
+
- Fully ClassMap-driven: every layout/surface/border/text/state class is
|
|
246
|
+
resolved through `getClassMap()` (`cm.pageShell`, `cm.page`, `cm.surface`,
|
|
247
|
+
`cm.borderR`, …), so swapping the ClassMap bond restyles the whole shell.
|
|
248
|
+
The sidebar WIDTH is applied via inline style from `sidebarWidth`
|
|
249
|
+
(`'sm'`|`'md'`|`'lg'`|pixel `number`); the old `sidebarWidthClass` prop is
|
|
250
|
+
`@deprecated` — parsed to pixels, never re-emitted as a class.
|
|
251
|
+
- `icon` values are Material Symbols ligature names rendered with the
|
|
252
|
+
`material-symbols-outlined` font class — the one documented icon-font
|
|
253
|
+
exception. Without the font loaded, the raw icon name shows as text.
|
|
254
|
+
- Active-nav highlighting picks the longest prefix-match of the current
|
|
255
|
+
path; same-path clicks get a `#top` fragment appended.
|
|
256
|
+
- `navAriaLabel` overrides the translated nav region name; without it the
|
|
257
|
+
label comes from `t('sidebarLayout.aria.primaryNavigation')` (English
|
|
258
|
+
default `'Primary navigation'`), so it follows a locale switch through its
|
|
259
|
+
companion locale bond (`@molecule/app-locales-sidebar-layout`). Nav item
|
|
260
|
+
`label`s stay plain caller strings — translate them upstream.
|
|
261
|
+
- Requires a bonded ClassMap. Sibling: `@molecule/app-shell-layout-vue` is
|
|
262
|
+
the top header/footer shell (router-free).
|
|
263
|
+
|
|
264
|
+
## Translations
|
|
10
265
|
|
|
11
|
-
|
|
266
|
+
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-vue",
|
|
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-vue",
|
|
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-ui": "1.
|
|
56
|
-
"@molecule/app-ui-vue": "1.1
|
|
57
|
-
"@molecule/app-vue": "3.
|
|
55
|
+
"@molecule/app-ui": "1.5.0",
|
|
56
|
+
"@molecule/app-ui-vue": "1.2.1",
|
|
57
|
+
"@molecule/app-vue": "3.9.0",
|
|
58
58
|
"@types/node": "26.6.5",
|
|
59
59
|
"jsdom": "30.1.3",
|
|
60
60
|
"typescript": "6.0.3",
|