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