@molecule/app-file-card-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 +398 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,405 @@
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:46:34.570Z
7
+ -->
8
+
1
9
  # @molecule/app-file-card-vue
2
10
 
3
- Vue file card primitives — icon, name, size, modified date, actions; grid + row layouts
11
+ Vue file card primitives.
12
+
13
+ Exports:
14
+
15
+ - `<FileCard>` — file representation card (icon/thumbnail + name + size + modified date + optional actions).
16
+ Two layouts: `'grid'` (square tile, default) and `'row'` (horizontal list line).
17
+ - `<FileIcon>` — stroke-currentColor SVG glyph keyed by `FileKind`.
18
+ - `bytes(value)` — pure helper that formats a byte count as `420 B` / `1.4 KB` / `2.3 MB` / etc.
19
+ - `sizeParts(value)` — the same split as `{ n, unit }`, for rendering the unit through `t()`.
20
+ - `relativeBucket(at, now?)` — pure helper that buckets a timestamp into `just-now` / `minutes` /
21
+ `hours` / `days` / `weeks` / `months` / `absolute`.
22
+ - `FileSummary` / `FileKind` / `SizeParts` types — stable shape for the consumer's domain model.
23
+
24
+ Used by cloud-file-manager (grid + list views), social-media + email-client
25
+ (attachment previews), and document-collaboration (sidebars).
26
+
27
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
28
+ > It is written to be read by coding agents as much as by people, and is generated from this
29
+ > package's source — edit `src/index.ts` JSDoc, not this file.
30
+
31
+ ## Quick Start
4
32
 
33
+ ```ts
34
+ import { createApp, defineComponent, h } from 'vue'
35
+ import { FileCard, type FileSummary } from '@molecule/app-file-card-vue'
36
+
37
+ const file: FileSummary = {
38
+ id: 'f-1',
39
+ name: 'Q3-report.pdf',
40
+ size: 482_137,
41
+ kind: 'document',
42
+ modifiedAt: '2026-04-30T18:23:00Z',
43
+ }
44
+
45
+ const Card = defineComponent({
46
+ setup() {
47
+ return () =>
48
+ h(FileCard, {
49
+ file,
50
+ layout: 'grid',
51
+ onClick: (f) => openFile(f.id),
52
+ actions: h(KebabMenu, { fileId: file.id }),
53
+ })
54
+ },
55
+ })
56
+
57
+ createApp(Card).mount('#app')
5
58
  ```
6
- npm install @molecule/app-file-card-vue
59
+
60
+ ## Type
61
+
62
+ `feature`
63
+
64
+ ## Installation
65
+
66
+ ```bash
67
+ npm install @molecule/app-file-card-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
68
+ ```
69
+
70
+ ## API
71
+
72
+ ### Interfaces
73
+
74
+ #### `SizeParts`
75
+
76
+ A formatted size's displayed number and its unit token, split for `t()`.
77
+
78
+ ```typescript
79
+ interface SizeParts {
80
+ /** The displayed number, rounded the way {@link bytes} displays it. */
81
+ n: string
82
+ /** The unit token the number counts. */
83
+ unit: SizeUnit
84
+ }
85
+ ```
86
+
87
+ #### `FileSummary`
88
+
89
+ Minimal description of a file shown in a `<FileCard>`. Apps map their own
90
+ domain types onto this shape — there is no required mime field; pass
91
+ `kind` instead so the icon matches even when only a filename is known.
92
+
93
+ ```typescript
94
+ interface FileSummary {
95
+ /** Stable identifier for the file (parent key + `data-mol-id` suffix). */
96
+ id: string
97
+ /** Display name (filename including extension). */
98
+ name: string
99
+ /** Size in bytes. Pass `0` for folders or unknown. */
100
+ size: number
101
+ /** File kind — drives the icon and the "kind" aria token. */
102
+ kind: FileKind
103
+ /** Last-modified timestamp (ISO string, ms epoch, or `Date`). Optional. */
104
+ modifiedAt?: string | number | Date
105
+ /** Optional thumbnail URL. When set, replaces the icon in `'grid'` layout. */
106
+ thumbnail?: string
107
+ }
7
108
  ```
8
109
 
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.
110
+ #### `FileCardProps`
111
+
112
+ Props for `<FileCard>`.
113
+
114
+ ```typescript
115
+ interface FileCardProps {
116
+ /** The file to render. */
117
+ file: FileSummary
118
+ /** Selected highlight state. */
119
+ selected?: boolean
120
+ /**
121
+ * Handler fired when the card body is activated: a click anywhere on it, or
122
+ * Enter / Space on its select button (a transparent button covering the card,
123
+ * with `aria-pressed` for `selected`). Not fired for the actions slot, which
124
+ * sits above that button.
125
+ */
126
+ onClick?: (file: FileSummary, event: MouseEvent) => void
127
+ /** Context-menu (right-click) handler. */
128
+ onContextMenu?: (file: FileSummary, event: MouseEvent) => void
129
+ /** Layout — `'grid'` (default) is a square tile, `'row'` is a horizontal list line. */
130
+ layout?: 'grid' | 'row'
131
+ /**
132
+ * Optional trailing action slot (button row, kebab menu). Clicks here do not
133
+ * fire `onClick`. Passed as a prop or as the same-named slot — both work.
134
+ */
135
+ actions?: VNodeChild
136
+ /** Reference "now" for relative-time formatting. Useful for testing/snapshots. */
137
+ now?: Date
138
+ /** Extra classes merged onto the root element. */
139
+ className?: string
140
+ /** Override the root `data-mol-id` (defaults to `file-card-${file.id}`). */
141
+ dataMolId?: string
142
+ }
143
+ ```
144
+
145
+ #### `FileIconProps`
146
+
147
+ Props for `<FileIcon>`.
148
+
149
+ ```typescript
150
+ interface FileIconProps {
151
+ /** File kind — picks the SVG glyph. */
152
+ kind: FileKind
153
+ /** Pixel size of the rendered SVG (default 24). */
154
+ size?: number
155
+ /** Optional aria-label. When omitted the icon is `aria-hidden`. */
156
+ ariaLabel?: string
157
+ }
158
+ ```
159
+
160
+ ### Types
161
+
162
+ #### `SizeUnit`
163
+
164
+ The unit token a formatted byte count ends in (`B` plus the binary steps).
165
+
166
+ ```typescript
167
+ type SizeUnit = 'B' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB'
168
+ ```
169
+
170
+ #### `RelativeBucket`
171
+
172
+ A relative-time bucket used to pick a translation key. Higher granularity
173
+ buckets first; falls through to absolute date when older than ~1 year.
174
+
175
+ ```typescript
176
+ type RelativeBucket =
177
+ | { kind: 'just-now' }
178
+ | { kind: 'minutes'; n: number }
179
+ | { kind: 'hours'; n: number }
180
+ | { kind: 'days'; n: number }
181
+ | { kind: 'weeks'; n: number }
182
+ | { kind: 'months'; n: number }
183
+ | { kind: 'absolute'; iso: string }
184
+ ```
185
+
186
+ #### `FileKind`
187
+
188
+ Supported file kinds. Drives icon selection and the "<kind>" portion of
189
+ the aria label translation key (e.g. `file-card.kind.image`).
190
+
191
+ ```typescript
192
+ type FileKind = 'image' | 'video' | 'audio' | 'document' | 'archive' | 'code' | 'folder' | 'other'
193
+ ```
194
+
195
+ ### Functions
196
+
197
+ #### `sizeParts(value)`
198
+
199
+ Split a non-negative byte count into its displayed number and unit token
200
+ (e.g. `420` + `B`, `1.4` + `KB`, `471` + `MB`) — the two halves
201
+ {@link bytes} joins, exposed so the card can translate the unit word via
202
+ `t()` (one literal key per {@link SizeUnit}, as the kind labels do).
203
+
204
+ Uses a 1024 base (binary) and 1 fractional digit for KB+. Returns the
205
+ `0 B` parts for non-finite or negative inputs so callers do not need to
206
+ pre-validate.
207
+
208
+ ```typescript
209
+ function sizeParts(value: number): SizeParts
210
+ ```
211
+
212
+ - `value` — Byte count (>= 0).
213
+
214
+ **Returns:** The displayed number and unit token.
215
+
216
+ #### `bytes(value)`
217
+
218
+ Format a non-negative byte count as a short human-readable string
219
+ (e.g. `420 B`, `1.4 KB`, `2.3 MB`, `4.7 GB`, `8.1 TB`).
220
+
221
+ The unlocalized join of {@link sizeParts}'s two halves, for callers that
222
+ want the raw SI shorthand. The card itself renders the unit through `t()`
223
+ (`file-card.size.<unit>` keys in the locale bond) so a locale switch
224
+ translates it; the unit token is universal SI shorthand — a language that
225
+ names bytes differently (French octets, Russian КБ) changes only the token,
226
+ never the magnitude.
227
+
228
+ ```typescript
229
+ function bytes(value: number): string
230
+ ```
231
+
232
+ - `value` — Byte count (>= 0).
233
+
234
+ **Returns:** Formatted size string.
235
+
236
+ #### `relativeBucket(at, now)`
237
+
238
+ Bucket a `Date` (or ISO string / ms timestamp) against `now` into a
239
+ relative-time bucket. The bucket is purely structural — translation keys
240
+ and pluralization are applied by the consumer.
241
+
242
+ ```typescript
243
+ function relativeBucket(at: string | number | Date, now?: Date): RelativeBucket
244
+ ```
245
+
246
+ - `at` — Modified-at timestamp (ISO string, ms epoch, or `Date`).
247
+ - `now` — Reference "now" (defaults to `new Date()`). Injected for tests.
248
+
249
+ **Returns:** A `RelativeBucket` describing the offset from `now`.
250
+
251
+ ### Constants
252
+
253
+ #### `FileCard`
254
+
255
+ File representation card — icon (or thumbnail), filename, formatted size,
256
+ relative modified date, and optional trailing actions slot. Used by
257
+ cloud-file-manager grids/lists, social-media + email-client attachment
258
+ previews, and document-collaboration sidebars.
259
+
260
+ Two layouts:
261
+
262
+ - `'grid'` (default) — square tile with the icon/thumbnail stacked above
263
+ the metadata. Suitable for finder-style grids and attachment galleries.
264
+ - `'row'` — horizontal line item with the icon on the left, metadata in
265
+ the middle, and the actions slot on the right. Suitable for list views
266
+ and chat/email attachment rows.
267
+
268
+ All styling routes through `getClassMap()`. All user-visible text routes
269
+ through `t()` so the card translates via the companion
270
+ `@molecule/app-locales-file-card` locale bond.
271
+
272
+ ```typescript
273
+ const FileCard: DefineComponent<
274
+ ExtractPropTypes<{
275
+ file: { type: PropType<FileSummary>; required: true }
276
+ selected: { type: BooleanConstructor; default: undefined }
277
+ onClick: { type: PropType<FileCardProps['onClick']>; default: undefined }
278
+ onContextMenu: { type: PropType<FileCardProps['onContextMenu']>; default: undefined }
279
+ layout: { type: PropType<'grid' | 'row'>; default: string }
280
+ actions: null
281
+ now: { type: PropType<Date>; default: undefined }
282
+ className: { type: StringConstructor; default: undefined }
283
+ dataMolId: { type: StringConstructor; default: undefined }
284
+ }>,
285
+ () => VNode,
286
+ {},
287
+ {},
288
+ {},
289
+ ComponentOptionsMixin,
290
+ ComponentOptionsMixin,
291
+ {},
292
+ string,
293
+ PublicProps,
294
+ Readonly<
295
+ ExtractPropTypes<{
296
+ file: { type: PropType<FileSummary>; required: true }
297
+ selected: { type: BooleanConstructor; default: undefined }
298
+ onClick: { type: PropType<FileCardProps['onClick']>; default: undefined }
299
+ onContextMenu: { type: PropType<FileCardProps['onContextMenu']>; default: undefined }
300
+ layout: { type: PropType<'grid' | 'row'>; default: string }
301
+ actions: null
302
+ now: { type: PropType<Date>; default: undefined }
303
+ className: { type: StringConstructor; default: undefined }
304
+ dataMolId: { type: StringConstructor; default: undefined }
305
+ }>
306
+ > &
307
+ Readonly<{}>,
308
+ {
309
+ onClick: ((file: FileSummary, event: MouseEvent) => void) | undefined
310
+ onContextMenu: ((file: FileSummary, event: MouseEvent) => void) | undefined
311
+ selected: boolean
312
+ layout: 'grid' | 'row'
313
+ now: Date
314
+ className: string
315
+ dataMolId: string
316
+ },
317
+ {},
318
+ {},
319
+ {},
320
+ string,
321
+ ComponentProvideOptions,
322
+ true,
323
+ {},
324
+ any
325
+ >
326
+ ```
327
+
328
+ - `props` — Component props (see {@link FileCardProps}).
329
+
330
+ **Returns:** The file card component.
331
+
332
+ #### `FileIcon`
333
+
334
+ Icon glyph for a file kind. Stroke-currentColor SVG so it inherits the
335
+ surrounding text color (no ClassMap colors needed).
336
+
337
+ ```typescript
338
+ const FileIcon: DefineComponent<
339
+ ExtractPropTypes<{
340
+ kind: { type: PropType<FileKind>; required: true }
341
+ size: { type: NumberConstructor; default: undefined }
342
+ ariaLabel: { type: StringConstructor; default: undefined }
343
+ }>,
344
+ () => VNode,
345
+ {},
346
+ {},
347
+ {},
348
+ ComponentOptionsMixin,
349
+ ComponentOptionsMixin,
350
+ {},
351
+ string,
352
+ PublicProps,
353
+ Readonly<
354
+ ExtractPropTypes<{
355
+ kind: { type: PropType<FileKind>; required: true }
356
+ size: { type: NumberConstructor; default: undefined }
357
+ ariaLabel: { type: StringConstructor; default: undefined }
358
+ }>
359
+ > &
360
+ Readonly<{}>,
361
+ { size: number; ariaLabel: string },
362
+ {},
363
+ {},
364
+ {},
365
+ string,
366
+ ComponentProvideOptions,
367
+ true,
368
+ {},
369
+ any
370
+ >
371
+ ```
372
+
373
+ - `props` — Component props (see {@link FileIconProps}).
374
+
375
+ **Returns:** The SVG icon component.
376
+
377
+ ## Injection Notes
378
+
379
+ ### Requirements
380
+
381
+ Peer dependencies:
382
+
383
+ - `@molecule/app-ui` ^1.0.1
384
+ - `@molecule/app-ui-vue` ^1.1.0
385
+ - `@molecule/app-vue` ^3.5.0
386
+ - `vue` ^3.4.0
387
+
388
+ ### Runtime Dependencies
389
+
390
+ - `@molecule/app-ui`
391
+ - `@molecule/app-ui-vue`
392
+ - `@molecule/app-vue`
393
+ - `vue`
394
+
395
+ All styling routes through `getClassMap()` from `@molecule/app-ui` —
396
+ swap the ClassMap bond to restyle without touching this package.
397
+
398
+ All user-visible text routes through `t()` (via `@molecule/app-vue`'s
399
+ `useTranslation`) and translates via the companion
400
+ `@molecule/app-locales-file-card` locale bond. English fallbacks are
401
+ inlined so the card works without the locale bond present.
402
+
403
+ ## Translations
10
404
 
11
- License: Apache-2.0
405
+ Translation strings are provided by `@molecule/app-locales-file-card`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-file-card-vue",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Vue file card primitives — icon, name, size, modified date, actions; grid + row layouts",
5
5
  "homepage": "https://www.molecule.dev/packages/app-file-card-vue",
6
6
  "type": "module",
@@ -53,9 +53,9 @@
53
53
  "@molecule/app-framework-conformance": "0.0.0",
54
54
  "@molecule/app-i18n": "1.2.2",
55
55
  "@molecule/app-icons": "1.0.4",
56
- "@molecule/app-ui": "1.4.0",
57
- "@molecule/app-ui-vue": "1.1.5",
58
- "@molecule/app-vue": "3.7.2",
56
+ "@molecule/app-ui": "1.5.0",
57
+ "@molecule/app-ui-vue": "1.2.1",
58
+ "@molecule/app-vue": "3.9.0",
59
59
  "@types/node": "26.6.5",
60
60
  "jsdom": "30.1.3",
61
61
  "typescript": "6.0.3",