@molecule/app-sidebar-layout-svelte 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 +183 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,190 @@
|
|
|
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.489Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-sidebar-layout-svelte
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Svelte 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 snippets; the main area on the right scrolls
|
|
16
|
+
and renders the routed view.
|
|
17
|
+
|
|
18
|
+
It is the Svelte 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 is the default snippet.
|
|
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
|
+
```svelte
|
|
29
|
+
<script lang="ts">
|
|
30
|
+
import { SidebarLayout } from '@molecule/app-sidebar-layout-svelte'
|
|
31
|
+
import type { SidebarNavItem } from '@molecule/app-sidebar-layout-svelte'
|
|
32
|
+
|
|
33
|
+
const NAV: SidebarNavItem[] = [
|
|
34
|
+
{ key: 'dashboard', to: '/dashboard', icon: 'dashboard', label: 'Dashboard' },
|
|
35
|
+
{ key: 'projects', to: '/projects', icon: 'folder', label: 'Projects' },
|
|
36
|
+
{ key: 'settings', to: '/settings', icon: 'settings', label: 'Settings' },
|
|
37
|
+
]
|
|
38
|
+
</script>
|
|
39
|
+
|
|
40
|
+
<SidebarLayout appName="Acme App" navItems={NAV}>
|
|
41
|
+
<RouterView />
|
|
42
|
+
</SidebarLayout>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Type
|
|
46
|
+
|
|
47
|
+
`feature`
|
|
48
|
+
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm install @molecule/app-sidebar-layout-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## API
|
|
56
|
+
|
|
57
|
+
### Interfaces
|
|
58
|
+
|
|
59
|
+
#### `SidebarNavItem`
|
|
60
|
+
|
|
61
|
+
Describes a single item in the sidebar's vertical navigation list.
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
interface SidebarNavItem {
|
|
65
|
+
/** Route path the link goes to. */
|
|
66
|
+
to: string
|
|
67
|
+
/** Stable key — used for list keys and i18n key suffix. */
|
|
68
|
+
key: string
|
|
69
|
+
/** Material symbol icon name. */
|
|
70
|
+
icon?: string
|
|
71
|
+
/** Visible label. Apps that route this through `t(...)` should pass the resolved string. */
|
|
72
|
+
label: string
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
#### `SidebarLayoutProps`
|
|
77
|
+
|
|
78
|
+
Props accepted by the {@link SidebarLayout} component.
|
|
4
79
|
|
|
80
|
+
```typescript
|
|
81
|
+
interface SidebarLayoutProps {
|
|
82
|
+
/** Brand text shown at the top of the sidebar (typically the app name). */
|
|
83
|
+
appName: string
|
|
84
|
+
/** Path the brand link navigates to. Defaults to `'/'`. */
|
|
85
|
+
logoTo?: string
|
|
86
|
+
/** Vertical nav items rendered in the sidebar. */
|
|
87
|
+
navItems: ReadonlyArray<SidebarNavItem>
|
|
88
|
+
/** Snippet rendered at the bottom of the sidebar (typically a user menu). */
|
|
89
|
+
userMenu?: Snippet
|
|
90
|
+
/** Optional snippet rendered next to the user menu (typically a theme toggle). */
|
|
91
|
+
themeToggle?: Snippet
|
|
92
|
+
/**
|
|
93
|
+
* Aria-label for the primary `<nav>`. Overrides the translated default
|
|
94
|
+
* (`sidebarLayout.aria.primaryNavigation`, English `'Primary navigation'`);
|
|
95
|
+
* prop > `t()` > default.
|
|
96
|
+
*/
|
|
97
|
+
navAriaLabel?: string
|
|
98
|
+
/**
|
|
99
|
+
* Sidebar width — a stack-agnostic preset (`'sm'` | `'md'` | `'lg'`) or an
|
|
100
|
+
* exact pixel `number`. Applied via inline style. Defaults to `'md'` (240px).
|
|
101
|
+
*/
|
|
102
|
+
sidebarWidth?: SidebarWidth
|
|
103
|
+
/**
|
|
104
|
+
* Legacy sidebar-width prop retained only for backward compatibility: a
|
|
105
|
+
* `w-<n>` value is PARSED to a pixel width and applied via inline style
|
|
106
|
+
* (never re-emitted as a class). `sidebarWidth` takes precedence.
|
|
107
|
+
*
|
|
108
|
+
* @deprecated Use {@link SidebarLayoutProps.sidebarWidth} instead.
|
|
109
|
+
*/
|
|
110
|
+
sidebarWidthClass?: string
|
|
111
|
+
/** Extra classes on the outer wrapper. */
|
|
112
|
+
className?: string
|
|
113
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
114
|
+
dataMolId?: string
|
|
115
|
+
/**
|
|
116
|
+
* The routed page body. React renders React Router's `<Outlet />` in the
|
|
117
|
+
* `<main>`; pass the routed view (the layout's page content) here.
|
|
118
|
+
*/
|
|
119
|
+
children?: Snippet
|
|
120
|
+
}
|
|
5
121
|
```
|
|
6
|
-
|
|
122
|
+
|
|
123
|
+
### Types
|
|
124
|
+
|
|
125
|
+
#### `SidebarWidth`
|
|
126
|
+
|
|
127
|
+
Semantic sidebar width. Mapped to a fixed pixel width internally and applied
|
|
128
|
+
via inline style (a width is one of the "specific values" a styling-agnostic
|
|
129
|
+
ClassMap cannot express as a swappable token) so the sidebar renders the same
|
|
130
|
+
regardless of which ClassMap bond is active — no Tailwind width utility leaks
|
|
131
|
+
into consumer code.
|
|
132
|
+
|
|
133
|
+
- `sm` → 208px, `md` → 240px (default), `lg` → 256px.
|
|
134
|
+
- Pass a raw `number` for an exact pixel width.
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
type SidebarWidth = 'sm' | 'md' | 'lg' | number
|
|
7
138
|
```
|
|
8
139
|
|
|
9
|
-
|
|
140
|
+
### Constants
|
|
141
|
+
|
|
142
|
+
#### `SidebarLayout`
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
const SidebarLayout: LegacyComponentType
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Injection Notes
|
|
149
|
+
|
|
150
|
+
### Requirements
|
|
151
|
+
|
|
152
|
+
Peer dependencies:
|
|
153
|
+
|
|
154
|
+
- `@molecule/app-svelte` ^3.6.0
|
|
155
|
+
- `@molecule/app-ui` ^1.3.11
|
|
156
|
+
- `@molecule/app-ui-svelte` ^1.1.0
|
|
157
|
+
- `svelte` ^5.0.0
|
|
158
|
+
|
|
159
|
+
### Runtime Dependencies
|
|
160
|
+
|
|
161
|
+
- `@molecule/app-svelte`
|
|
162
|
+
- `@molecule/app-ui`
|
|
163
|
+
- `@molecule/app-ui-svelte`
|
|
164
|
+
- `svelte`
|
|
165
|
+
|
|
166
|
+
- Router required: reads the current location and renders router links, so
|
|
167
|
+
it must be mounted inside the molecule router provider (the app shell
|
|
168
|
+
does that at startup).
|
|
169
|
+
- Fully ClassMap-driven: every layout/surface/border/text/state class is
|
|
170
|
+
resolved through `getClassMap()` (`cm.pageShell`, `cm.page`, `cm.surface`,
|
|
171
|
+
`cm.borderR`, …), so swapping the ClassMap bond restyles the whole shell.
|
|
172
|
+
The sidebar WIDTH is applied via inline style from `sidebarWidth`
|
|
173
|
+
(`'sm'`|`'md'`|`'lg'`|pixel `number`); the old `sidebarWidthClass` prop is
|
|
174
|
+
`@deprecated` — parsed to pixels, never re-emitted as a class.
|
|
175
|
+
- `icon` values are Material Symbols ligature names rendered with the
|
|
176
|
+
`material-symbols-outlined` font class — the one documented icon-font
|
|
177
|
+
exception. Without the font loaded, the raw icon name shows as text.
|
|
178
|
+
- Active-nav highlighting picks the longest prefix-match of the current
|
|
179
|
+
path; same-path clicks get a `#top` fragment appended.
|
|
180
|
+
- `navAriaLabel` overrides the translated nav region name; without it the
|
|
181
|
+
label comes from `t('sidebarLayout.aria.primaryNavigation')` (English
|
|
182
|
+
default `'Primary navigation'`), so it follows a locale switch through its
|
|
183
|
+
companion locale bond (`@molecule/app-locales-sidebar-layout`). Nav item
|
|
184
|
+
`label`s stay plain caller strings — translate them upstream.
|
|
185
|
+
- Requires a bonded ClassMap. Sibling: `@molecule/app-shell-layout-svelte`
|
|
186
|
+
is the top header/footer shell (router-free).
|
|
187
|
+
|
|
188
|
+
## Translations
|
|
10
189
|
|
|
11
|
-
|
|
190
|
+
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-svelte",
|
|
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-svelte",
|
|
6
6
|
"type": "module",
|
|
@@ -58,9 +58,9 @@
|
|
|
58
58
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
59
59
|
"@molecule/app-i18n": "1.2.2",
|
|
60
60
|
"@molecule/app-icons": "1.0.4",
|
|
61
|
-
"@molecule/app-svelte": "3.
|
|
62
|
-
"@molecule/app-ui": "1.
|
|
63
|
-
"@molecule/app-ui-svelte": "1.1
|
|
61
|
+
"@molecule/app-svelte": "3.9.0",
|
|
62
|
+
"@molecule/app-ui": "1.5.0",
|
|
63
|
+
"@molecule/app-ui-svelte": "1.2.1",
|
|
64
64
|
"@sveltejs/package": "3.0.2",
|
|
65
65
|
"@sveltejs/vite-plugin-svelte": "7.1.2",
|
|
66
66
|
"@types/node": "26.6.5",
|