@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.
Files changed (2) hide show
  1. package/README.md +183 -4
  2. 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
- Vertical sidebar app shell: brand block + vertical NavLinks + user-menu slot, with a router outlet for nested routes
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
- npm install @molecule/app-sidebar-layout-svelte
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
- 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.
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
- License: Apache-2.0
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": "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-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.7.2",
62
- "@molecule/app-ui": "1.4.0",
63
- "@molecule/app-ui-svelte": "1.1.7",
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",