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