@molecule/app-file-card-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 +276 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,283 @@
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.337Z
7
+ -->
8
+
1
9
  # @molecule/app-file-card-svelte
2
10
 
3
- Svelte file card primitives — icon, name, size, modified date, actions; grid + row layouts
11
+ Svelte 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
32
+
33
+ ```svelte
34
+ <script lang="ts">
35
+ import { FileCard, type FileSummary } from '@molecule/app-file-card-svelte'
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
+ </script>
45
+
46
+ <FileCard {file} layout="grid" onClick={(f) => openFile(f.id)}>
47
+ {#snippet actions()}
48
+ <KebabMenu fileId={file.id} />
49
+ {/snippet}
50
+ </FileCard>
51
+ ```
52
+
53
+ ## Type
54
+
55
+ `feature`
56
+
57
+ ## Installation
58
+
59
+ ```bash
60
+ npm install @molecule/app-file-card-svelte @molecule/app-svelte @molecule/app-ui @molecule/app-ui-svelte svelte
61
+ ```
62
+
63
+ ## API
64
+
65
+ ### Interfaces
66
+
67
+ #### `SizeParts`
68
+
69
+ A formatted size's displayed number and its unit token, split for `t()`.
70
+
71
+ ```typescript
72
+ interface SizeParts {
73
+ /** The displayed number, rounded the way {@link bytes} displays it. */
74
+ n: string
75
+ /** The unit token the number counts. */
76
+ unit: SizeUnit
77
+ }
78
+ ```
79
+
80
+ #### `FileSummary`
81
+
82
+ Minimal description of a file shown in a `<FileCard>`. Apps map their own
83
+ domain types onto this shape — there is no required mime field; pass
84
+ `kind` instead so the icon matches even when only a filename is known.
85
+
86
+ ```typescript
87
+ interface FileSummary {
88
+ /** Stable identifier for the file (parent key + `data-mol-id` suffix). */
89
+ id: string
90
+ /** Display name (filename including extension). */
91
+ name: string
92
+ /** Size in bytes. Pass `0` for folders or unknown. */
93
+ size: number
94
+ /** File kind — drives the icon and the "kind" aria token. */
95
+ kind: FileKind
96
+ /** Last-modified timestamp (ISO string, ms epoch, or `Date`). Optional. */
97
+ modifiedAt?: string | number | Date
98
+ /** Optional thumbnail URL. When set, replaces the icon in `'grid'` layout. */
99
+ thumbnail?: string
100
+ }
101
+ ```
102
+
103
+ #### `FileCardProps`
104
+
105
+ Props for `<FileCard>`.
106
+
107
+ ```typescript
108
+ interface FileCardProps {
109
+ /** The file to render. */
110
+ file: FileSummary
111
+ /** Selected highlight state. */
112
+ selected?: boolean
113
+ /**
114
+ * Handler fired when the card body is activated: a click anywhere on it, or
115
+ * Enter / Space on its select button (a transparent button covering the card,
116
+ * with `aria-pressed` for `selected`). Not fired for the actions slot, which
117
+ * sits above that button.
118
+ */
119
+ onClick?: (file: FileSummary, event: MouseEvent) => void
120
+ /** Context-menu (right-click) handler. */
121
+ onContextMenu?: (file: FileSummary, event: MouseEvent) => void
122
+ /** Layout — `'grid'` (default) is a square tile, `'row'` is a horizontal list line. */
123
+ layout?: 'grid' | 'row'
124
+ /** Optional trailing action slot (button row, kebab menu). Clicks here do not fire `onClick`. */
125
+ actions?: Snippet
126
+ /** Reference "now" for relative-time formatting. Useful for testing/snapshots. */
127
+ now?: Date
128
+ /** Extra classes merged onto the root element. */
129
+ className?: string
130
+ /** Override the root `data-mol-id` (defaults to `file-card-${file.id}`). */
131
+ dataMolId?: string
132
+ }
133
+ ```
134
+
135
+ #### `FileIconProps`
4
136
 
137
+ Props for `<FileIcon>`.
138
+
139
+ ```typescript
140
+ interface FileIconProps {
141
+ /** File kind — picks the SVG glyph. */
142
+ kind: FileKind
143
+ /** Pixel size of the rendered SVG (default 24). */
144
+ size?: number
145
+ /** Optional aria-label. When omitted the icon is `aria-hidden`. */
146
+ ariaLabel?: string
147
+ }
148
+ ```
149
+
150
+ ### Types
151
+
152
+ #### `SizeUnit`
153
+
154
+ The unit token a formatted byte count ends in (`B` plus the binary steps).
155
+
156
+ ```typescript
157
+ type SizeUnit = 'B' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB'
5
158
  ```
6
- npm install @molecule/app-file-card-svelte
159
+
160
+ #### `RelativeBucket`
161
+
162
+ A relative-time bucket used to pick a translation key. Higher granularity
163
+ buckets first; falls through to absolute date when older than ~1 year.
164
+
165
+ ```typescript
166
+ type RelativeBucket =
167
+ | { kind: 'just-now' }
168
+ | { kind: 'minutes'; n: number }
169
+ | { kind: 'hours'; n: number }
170
+ | { kind: 'days'; n: number }
171
+ | { kind: 'weeks'; n: number }
172
+ | { kind: 'months'; n: number }
173
+ | { kind: 'absolute'; iso: string }
7
174
  ```
8
175
 
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.
176
+ #### `FileKind`
177
+
178
+ Supported file kinds. Drives icon selection and the "<kind>" portion of
179
+ the aria label translation key (e.g. `file-card.kind.image`).
180
+
181
+ ```typescript
182
+ type FileKind = 'image' | 'video' | 'audio' | 'document' | 'archive' | 'code' | 'folder' | 'other'
183
+ ```
184
+
185
+ ### Functions
186
+
187
+ #### `sizeParts(value)`
188
+
189
+ Split a non-negative byte count into its displayed number and unit token
190
+ (e.g. `420` + `B`, `1.4` + `KB`, `471` + `MB`) — the two halves
191
+ {@link bytes} joins, exposed so the card can translate the unit word via
192
+ `t()` (one literal key per {@link SizeUnit}, as the kind labels do).
193
+
194
+ Uses a 1024 base (binary) and 1 fractional digit for KB+. Returns the
195
+ `0 B` parts for non-finite or negative inputs so callers do not need to
196
+ pre-validate.
197
+
198
+ ```typescript
199
+ function sizeParts(value: number): SizeParts
200
+ ```
201
+
202
+ - `value` — Byte count (>= 0).
203
+
204
+ **Returns:** The displayed number and unit token.
205
+
206
+ #### `bytes(value)`
207
+
208
+ Format a non-negative byte count as a short human-readable string
209
+ (e.g. `420 B`, `1.4 KB`, `2.3 MB`, `4.7 GB`, `8.1 TB`).
210
+
211
+ The unlocalized join of {@link sizeParts}'s two halves, for callers that
212
+ want the raw SI shorthand. The card itself renders the unit through `t()`
213
+ (`file-card.size.<unit>` keys in the locale bond) so a locale switch
214
+ translates it; the unit token is universal SI shorthand — a language that
215
+ names bytes differently (French octets, Russian КБ) changes only the token,
216
+ never the magnitude.
217
+
218
+ ```typescript
219
+ function bytes(value: number): string
220
+ ```
221
+
222
+ - `value` — Byte count (>= 0).
223
+
224
+ **Returns:** Formatted size string.
225
+
226
+ #### `relativeBucket(at, now)`
227
+
228
+ Bucket a `Date` (or ISO string / ms timestamp) against `now` into a
229
+ relative-time bucket. The bucket is purely structural — translation keys
230
+ and pluralization are applied by the consumer.
231
+
232
+ ```typescript
233
+ function relativeBucket(at: string | number | Date, now?: Date): RelativeBucket
234
+ ```
235
+
236
+ - `at` — Modified-at timestamp (ISO string, ms epoch, or `Date`).
237
+ - `now` — Reference "now" (defaults to `new Date()`). Injected for tests.
238
+
239
+ **Returns:** A `RelativeBucket` describing the offset from `now`.
240
+
241
+ ### Constants
242
+
243
+ #### `FileCard`
244
+
245
+ ```typescript
246
+ const FileCard: LegacyComponentType
247
+ ```
248
+
249
+ #### `FileIcon`
250
+
251
+ ```typescript
252
+ const FileIcon: LegacyComponentType
253
+ ```
254
+
255
+ ## Injection Notes
256
+
257
+ ### Requirements
258
+
259
+ Peer dependencies:
260
+
261
+ - `@molecule/app-svelte` ^3.5.0
262
+ - `@molecule/app-ui` ^1.0.1
263
+ - `@molecule/app-ui-svelte` ^1.1.0
264
+ - `svelte` ^5.0.0
265
+
266
+ ### Runtime Dependencies
267
+
268
+ - `@molecule/app-svelte`
269
+ - `@molecule/app-ui`
270
+ - `@molecule/app-ui-svelte`
271
+ - `svelte`
272
+
273
+ All styling routes through `getClassMap()` from `@molecule/app-ui` —
274
+ swap the ClassMap bond to restyle without touching this package.
275
+
276
+ All user-visible text routes through `t()` (via `@molecule/app-svelte`'s
277
+ `useTranslation`) and translates via the companion
278
+ `@molecule/app-locales-file-card` locale bond. English fallbacks are
279
+ inlined so the card works without the locale bond present.
280
+
281
+ ## Translations
10
282
 
11
- License: Apache-2.0
283
+ 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-svelte",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Svelte file card primitives — icon, name, size, modified date, actions; grid + row layouts",
5
5
  "homepage": "https://www.molecule.dev/packages/app-file-card-svelte",
6
6
  "type": "module",
@@ -59,9 +59,9 @@
59
59
  "@molecule/app-framework-conformance": "0.0.0",
60
60
  "@molecule/app-i18n": "1.2.2",
61
61
  "@molecule/app-icons": "1.0.4",
62
- "@molecule/app-svelte": "3.7.2",
63
- "@molecule/app-ui": "1.4.0",
64
- "@molecule/app-ui-svelte": "1.1.7",
62
+ "@molecule/app-svelte": "3.9.0",
63
+ "@molecule/app-ui": "1.5.0",
64
+ "@molecule/app-ui-svelte": "1.2.1",
65
65
  "@sveltejs/package": "3.0.2",
66
66
  "@sveltejs/vite-plugin-svelte": "7.1.2",
67
67
  "@types/node": "26.6.5",