@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.
Files changed (2) hide show
  1. package/README.md +259 -4
  2. 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
- Vertical sidebar app shell: brand block + vertical NavLinks + user-menu slot, with a router outlet for nested routes
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
- npm install @molecule/app-sidebar-layout-vue
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
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
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
- License: Apache-2.0
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": "0.0.1-stage",
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.4.0",
56
- "@molecule/app-ui-vue": "1.1.5",
57
- "@molecule/app-vue": "3.7.2",
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",