@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.
- package/README.md +301 -4
- 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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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": "
|
|
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.
|
|
57
|
-
"@molecule/app-ui": "1.
|
|
58
|
-
"@molecule/app-ui-solid": "1.1
|
|
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",
|