@molecule/app-settings-container-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 +419 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,426 @@
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:16.998Z
7
+ -->
8
+
1
9
  # @molecule/app-settings-container-vue
2
10
 
3
- Vue layout for Settings pages (sidebar + content + section cards)
11
+ Vue Settings-page scaffold (layout chrome only).
12
+
13
+ Exports:
14
+
15
+ - `<SettingsLayout>` — two-column [sidebar, content] with an optional
16
+ `header` slot rendered above both.
17
+ - `<SettingsSidebar>` — controlled side-nav (`items`, `activeId`,
18
+ `onSelect`, optional `footer`); `SettingsSidebarItem` is
19
+ `{ id, label, icon? }`.
20
+ - `<SettingsContent>` — stacked wrapper for the right column.
21
+ - `<SettingsSection>` — Card-wrapped titled section (`title`,
22
+ `description?`, `footer?` action row, `dataMolId?`).
23
+
24
+ It is the Vue counterpart of `@molecule/app-settings-container-react`: the
25
+ same props (React names), the same ClassMap tokens, and the same DOM for the
26
+ same input, so an app moves between frameworks by changing the package name
27
+ in its imports.
28
+
29
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
30
+ > It is written to be read by coding agents as much as by people, and is generated from this
31
+ > package's source — edit `src/index.ts` JSDoc, not this file.
32
+
33
+ ## Quick Start
34
+
35
+ ```ts
36
+ import { defineComponent, h, ref } from 'vue'
37
+
38
+ import {
39
+ SettingsContent,
40
+ SettingsLayout,
41
+ SettingsSection,
42
+ SettingsSidebar,
43
+ } from '@molecule/app-settings-container-vue'
44
+
45
+ const NAV = [
46
+ { id: 'profile', label: 'Profile' },
47
+ { id: 'notifications', label: 'Notifications' },
48
+ ]
49
+
50
+ export const SettingsPage = defineComponent({
51
+ setup() {
52
+ const active = ref('profile')
53
+ return () =>
54
+ h(SettingsLayout, null, {
55
+ sidebar: () => [
56
+ h(SettingsSidebar, {
57
+ items: NAV,
58
+ activeId: active.value,
59
+ onSelect: (id: string) => (active.value = id),
60
+ }),
61
+ ],
62
+ default: () => [
63
+ h(SettingsContent, null, {
64
+ default: () => [
65
+ h(
66
+ SettingsSection,
67
+ {
68
+ title: 'Profile',
69
+ description: 'Update your display name and avatar.',
70
+ },
71
+ { default: () => [h('p', null, 'Form fields go here.')] },
72
+ ),
73
+ ],
74
+ }),
75
+ ],
76
+ })
77
+ },
78
+ })
79
+ ```
80
+
81
+ ## Type
82
+
83
+ `feature`
84
+
85
+ ## Installation
86
+
87
+ ```bash
88
+ npm install @molecule/app-settings-container-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
89
+ ```
90
+
91
+ ## API
92
+
93
+ ### Interfaces
94
+
95
+ #### `SettingsLayoutProps`
96
+
97
+ Props accepted by the {@link SettingsLayout} component.
98
+
99
+ ```typescript
100
+ interface SettingsLayoutProps {
101
+ /**
102
+ * Left-side navigation (typically `<SettingsSidebar>`). Passed as a prop or
103
+ * as the same-named slot — both work.
104
+ */
105
+ sidebar?: VNodeChild
106
+ /** Main content area — the DEFAULT slot (usually one or more `<SettingsSection>`s). */
107
+ children?: VNodeChild
108
+ /**
109
+ * Optional header (breadcrumb, title, save button) rendered above both
110
+ * columns. NOT sticky — apply your own sticky positioning if needed. Passed
111
+ * as a prop or as the same-named slot.
112
+ */
113
+ header?: VNodeChild
114
+ /** Extra classes on the outer wrapper. */
115
+ className?: string
116
+ /** `data-mol-id` for AI-agent selectors. */
117
+ dataMolId?: string
118
+ }
119
+ ```
120
+
121
+ #### `SettingsContentProps`
122
+
123
+ Props accepted by the {@link SettingsContent} component.
124
+
125
+ ```typescript
126
+ interface SettingsContentProps {
127
+ /** Active section content — the DEFAULT slot. */
128
+ children?: VNodeChild
129
+ /** Extra classes. */
130
+ className?: string
131
+ }
132
+ ```
133
+
134
+ #### `SettingsSidebarItem`
135
+
136
+ A single navigable item in the settings sidebar.
137
+
138
+ ```typescript
139
+ interface SettingsSidebarItem {
140
+ /** Unique id; the active item is the one whose id equals `activeId`. */
141
+ id: string
142
+ /** Visible label (a VNode or plain text). */
143
+ label: VNodeChild
144
+ /** Optional leading icon (a VNode). */
145
+ icon?: VNodeChild
146
+ }
147
+ ```
148
+
149
+ #### `SettingsSidebarProps`
150
+
151
+ Props accepted by the {@link SettingsSidebar} component.
152
+
153
+ ```typescript
154
+ interface SettingsSidebarProps {
155
+ /** Items to render, in order. */
156
+ items: SettingsSidebarItem[]
157
+ /** The id of the active item (controlled — the caller owns it). */
158
+ activeId: string
159
+ /** Called with the clicked item's id. */
160
+ onSelect: (id: string) => void
161
+ /**
162
+ * Optional footer inside the sidebar (sign-out, plan indicator). Passed as a
163
+ * prop or as the same-named slot.
164
+ */
165
+ footer?: VNodeChild
166
+ /**
167
+ * Accessible name for the `<nav>` region. Overrides the translated /
168
+ * `defaultValue` `'Settings'` (prop > `t()` > default).
169
+ */
170
+ ariaLabel?: string
171
+ /** Extra classes. */
172
+ className?: string
173
+ }
174
+ ```
175
+
176
+ #### `SettingsSectionProps`
177
+
178
+ Props accepted by the {@link SettingsSection} component.
179
+
180
+ ```typescript
181
+ interface SettingsSectionProps {
182
+ /** Section heading. Passed as a prop or as the same-named slot. */
183
+ title?: VNodeChild
184
+ /**
185
+ * Optional description under the heading. Passed as a prop or as the
186
+ * same-named slot.
187
+ */
188
+ description?: VNodeChild
189
+ /** Section body — the DEFAULT slot. */
190
+ children?: VNodeChild
191
+ /**
192
+ * Optional footer row (save button, last-saved indicator). Passed as a prop
193
+ * or as the same-named slot.
194
+ */
195
+ footer?: VNodeChild
196
+ /** Extra classes on the Card. */
197
+ className?: string
198
+ /** `data-mol-id` for AI-agent selectors. */
199
+ dataMolId?: string
200
+ }
201
+ ```
202
+
203
+ ### Constants
204
+
205
+ #### `SettingsContent`
206
+
207
+ Wrapper for the right-hand column of `<SettingsLayout>`. Just a
208
+ vertically-stacked container for one or more `<SettingsSection>`s — useful
209
+ as a semantic landmark and for consistent spacing.
210
+
211
+ ```typescript
212
+ const SettingsContent: DefineComponent<
213
+ ExtractPropTypes<{ className: PropType<SettingsContentProps['className']> }>,
214
+ () => VNode,
215
+ {},
216
+ {},
217
+ {},
218
+ ComponentOptionsMixin,
219
+ ComponentOptionsMixin,
220
+ {},
221
+ string,
222
+ PublicProps,
223
+ Readonly<ExtractPropTypes<{ className: PropType<SettingsContentProps['className']> }>> &
224
+ Readonly<{}>,
225
+ {},
226
+ {},
227
+ {},
228
+ {},
229
+ string,
230
+ ComponentProvideOptions,
231
+ true,
232
+ {},
233
+ any
234
+ >
235
+ ```
236
+
237
+ - `props` — Component props (see {@link SettingsContentProps}).
238
+
239
+ **Returns:** The settings content component.
240
+
241
+ #### `SettingsLayout`
242
+
243
+ Two-column Settings page scaffold: sidebar on the left, content on the
244
+ right, optional (non-sticky) header above both.
245
+
246
+ ```typescript
247
+ const SettingsLayout: DefineComponent<
248
+ ExtractPropTypes<{
249
+ sidebar: null
250
+ header: null
251
+ className: PropType<SettingsLayoutProps['className']>
252
+ dataMolId: PropType<SettingsLayoutProps['dataMolId']>
253
+ }>,
254
+ () => VNode,
255
+ {},
256
+ {},
257
+ {},
258
+ ComponentOptionsMixin,
259
+ ComponentOptionsMixin,
260
+ {},
261
+ string,
262
+ PublicProps,
263
+ Readonly<
264
+ ExtractPropTypes<{
265
+ sidebar: null
266
+ header: null
267
+ className: PropType<SettingsLayoutProps['className']>
268
+ dataMolId: PropType<SettingsLayoutProps['dataMolId']>
269
+ }>
270
+ > &
271
+ Readonly<{}>,
272
+ {},
273
+ {},
274
+ {},
275
+ {},
276
+ string,
277
+ ComponentProvideOptions,
278
+ true,
279
+ {},
280
+ any
281
+ >
282
+ ```
283
+
284
+ - `props` — Component props (see {@link SettingsLayoutProps}).
285
+
286
+ **Returns:** The settings layout component.
4
287
 
288
+ #### `SettingsSection`
289
+
290
+ One configuration section inside a Settings page — Card-wrapped, with
291
+ title / description header, body slot, and optional footer action row.
292
+
293
+ ```typescript
294
+ const SettingsSection: DefineComponent<
295
+ ExtractPropTypes<{
296
+ title: null
297
+ description: null
298
+ footer: null
299
+ className: PropType<SettingsSectionProps['className']>
300
+ dataMolId: PropType<SettingsSectionProps['dataMolId']>
301
+ }>,
302
+ () => VNode,
303
+ {},
304
+ {},
305
+ {},
306
+ ComponentOptionsMixin,
307
+ ComponentOptionsMixin,
308
+ {},
309
+ string,
310
+ PublicProps,
311
+ Readonly<
312
+ ExtractPropTypes<{
313
+ title: null
314
+ description: null
315
+ footer: null
316
+ className: PropType<SettingsSectionProps['className']>
317
+ dataMolId: PropType<SettingsSectionProps['dataMolId']>
318
+ }>
319
+ > &
320
+ Readonly<{}>,
321
+ {},
322
+ {},
323
+ {},
324
+ {},
325
+ string,
326
+ ComponentProvideOptions,
327
+ true,
328
+ {},
329
+ any
330
+ >
5
331
  ```
6
- npm install @molecule/app-settings-container-vue
332
+
333
+ - `props` — Component props (see {@link SettingsSectionProps}).
334
+
335
+ **Returns:** The settings section component.
336
+
337
+ #### `SettingsSidebar`
338
+
339
+ Vertical side-nav for Settings pages. Controlled — the caller owns
340
+ `activeId`; every item calls `onSelect` with its id.
341
+
342
+ The nav region's accessible name resolves through `t()` with the
343
+ `settingsContainer.aria.settings` key, so it follows the active locale;
344
+ `ariaLabel` overrides it.
345
+
346
+ ```typescript
347
+ const SettingsSidebar: DefineComponent<
348
+ ExtractPropTypes<{
349
+ items: { type: PropType<SettingsSidebarProps['items']>; default: () => never[] }
350
+ activeId: PropType<SettingsSidebarProps['activeId']>
351
+ onSelect: PropType<SettingsSidebarProps['onSelect']>
352
+ footer: null
353
+ ariaLabel: { type: StringConstructor; default: undefined }
354
+ className: PropType<SettingsSidebarProps['className']>
355
+ }>,
356
+ () => VNode,
357
+ {},
358
+ {},
359
+ {},
360
+ ComponentOptionsMixin,
361
+ ComponentOptionsMixin,
362
+ {},
363
+ string,
364
+ PublicProps,
365
+ Readonly<
366
+ ExtractPropTypes<{
367
+ items: { type: PropType<SettingsSidebarProps['items']>; default: () => never[] }
368
+ activeId: PropType<SettingsSidebarProps['activeId']>
369
+ onSelect: PropType<SettingsSidebarProps['onSelect']>
370
+ footer: null
371
+ ariaLabel: { type: StringConstructor; default: undefined }
372
+ className: PropType<SettingsSidebarProps['className']>
373
+ }>
374
+ > &
375
+ Readonly<{}>,
376
+ { items: SettingsSidebarItem[]; ariaLabel: string },
377
+ {},
378
+ {},
379
+ {},
380
+ string,
381
+ ComponentProvideOptions,
382
+ true,
383
+ {},
384
+ any
385
+ >
7
386
  ```
8
387
 
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.
388
+ - `props` — Component props (see {@link SettingsSidebarProps}).
389
+
390
+ **Returns:** The settings sidebar component.
391
+
392
+ ## Injection Notes
393
+
394
+ ### Requirements
395
+
396
+ Peer dependencies:
397
+
398
+ - `@molecule/app-ui` ^1.0.1
399
+ - `@molecule/app-ui-vue` ^1.1.0
400
+ - `@molecule/app-vue` ^3.5.0
401
+ - `vue` ^3.4.0
402
+
403
+ ### Runtime Dependencies
404
+
405
+ - `@molecule/app-ui`
406
+ - `@molecule/app-ui-vue`
407
+ - `@molecule/app-vue`
408
+ - `vue`
409
+
410
+ - The `header` slot is rendered above the columns but is NOT sticky —
411
+ apply your own sticky positioning if you need it pinned.
412
+ - The two columns do not collapse responsively — swap the sidebar for a
413
+ drawer on small screens yourself.
414
+ - Requires a bonded ClassMap. Labels are your own nodes (translate
415
+ upstream); the sidebar nav's `aria-label="Settings"` is hardcoded
416
+ English.
417
+ - Don't confuse with `@molecule/app-settings-panel-vue`: that package is the
418
+ batteries-included panel (prebuilt Account/Auth/Billing/… sections wired
419
+ to molecule APIs). THIS package is empty layout chrome for building your
420
+ own settings pages.
421
+ - Node-valued props (`header`, `sidebar`, `footer`, `title`, `description`)
422
+ arrive as a prop AND a same-named slot; components accept either.
423
+
424
+ ## Translations
10
425
 
11
- License: Apache-2.0
426
+ Translation strings are provided by `@molecule/app-locales-settings-container`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-settings-container-vue",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Vue layout for Settings pages (sidebar + content + section cards)",
5
5
  "homepage": "https://www.molecule.dev/packages/app-settings-container-vue",
6
6
  "type": "module",
@@ -51,9 +51,9 @@
51
51
  "@molecule/app-framework-conformance": "0.0.0",
52
52
  "@molecule/app-i18n": "1.2.2",
53
53
  "@molecule/app-icons": "1.0.4",
54
- "@molecule/app-ui": "1.4.0",
55
- "@molecule/app-ui-vue": "1.1.5",
56
- "@molecule/app-vue": "3.7.2",
54
+ "@molecule/app-ui": "1.5.0",
55
+ "@molecule/app-ui-vue": "1.2.1",
56
+ "@molecule/app-vue": "3.9.0",
57
57
  "@types/node": "26.6.5",
58
58
  "jsdom": "30.1.3",
59
59
  "typescript": "6.0.3",