@molecule/app-file-card-angular 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 +545 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,552 @@
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:33.960Z
7
+ -->
8
+
1
9
  # @molecule/app-file-card-angular
2
10
 
3
- Angular file card primitives — icon, name, size, modified date, actions; grid + row layouts
11
+ Angular file card primitives — the Angular counterpart of
12
+ `@molecule/app-file-card-react`: the same props and the same DOM for the
13
+ same input.
14
+
15
+ Exports:
16
+
17
+ - `<FileCard>` — file representation card (icon/thumbnail + name + size + modified date + optional actions).
18
+ Two layouts: `'grid'` (square tile, default) and `'row'` (horizontal list line).
19
+ - `<FileIcon>` — stroke-currentColor SVG glyph keyed by `FileKind`.
20
+ - `bytes(value)` — pure helper that formats a byte count as `420 B` / `1.4 KB` / `2.3 MB` / etc.
21
+ - `sizeParts(value)` — the same split as `{ n, unit }`, for rendering the unit through `t()`.
22
+ - `relativeBucket(at, now?)` — pure helper that buckets a timestamp into `just-now` / `minutes` /
23
+ `hours` / `days` / `weeks` / `months` / `absolute`.
24
+ - `FileSummary` / `FileKind` / `SizeParts` types — stable shape for the consumer's domain model.
25
+
26
+ Used by cloud-file-manager (grid + list views), social-media + email-client
27
+ (attachment previews), and document-collaboration (sidebars).
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 { Component } from '@angular/core'
37
+ import { FileCard } from '@molecule/app-file-card-angular'
38
+
39
+ @Component({
40
+ selector: 'app-attachment',
41
+ standalone: true,
42
+ imports: [FileCard],
43
+ template: `
44
+ <div mol-file-card [file]="file" [layout]="'grid'" (onClick)="open(file.id)">
45
+ <button type="button" slot="actions" (click)="menu($event)">⋯</button>
46
+ </div>
47
+ `,
48
+ })
49
+ export class Attachment {}
50
+ ```
51
+
52
+ ## Type
53
+
54
+ `feature`
55
+
56
+ ## Installation
57
+
58
+ ```bash
59
+ npm install @molecule/app-file-card-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
60
+ ```
61
+
62
+ ## API
63
+
64
+ ### Interfaces
65
+
66
+ #### `SizeParts`
4
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
+ }
5
77
  ```
6
- npm install @molecule/app-file-card-angular
78
+
79
+ #### `FileSummary`
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 accepted by `<FileCard>` — the same props
105
+ `@molecule/app-file-card-react` accepts. Node props (`actions`) are
106
+ projected content in Angular (an input cannot carry a node), so `actions`
107
+ is typed `unknown`: pass it in the host template as `[slot=actions]`.
108
+
109
+ ```typescript
110
+ interface FileCardProps {
111
+ /** The file to render. */
112
+ file: FileSummary
113
+ /** Selected highlight state. */
114
+ selected?: boolean
115
+ /**
116
+ * Handler fired when the card body is activated: a click anywhere on it, or
117
+ * Enter / Space on its select button (a transparent button covering the card,
118
+ * with `aria-pressed` for `selected`). Not fired for the actions slot, which
119
+ * sits above that button.
120
+ */
121
+ onClick?: (file: FileSummary, event: MouseEvent) => void
122
+ /** Context-menu (right-click) handler. */
123
+ onContextMenu?: (file: FileSummary, event: MouseEvent) => void
124
+ /** Layout — `'grid'` (default) is a square tile, `'row'` is a horizontal list line. */
125
+ layout?: 'grid' | 'row'
126
+ /** Optional trailing action slot, projected as `[slot=actions]` content. */
127
+ actions?: unknown
128
+ /** Reference "now" for relative-time formatting. Useful for testing/snapshots. */
129
+ now?: Date
130
+ /** Extra classes merged onto the root element. */
131
+ className?: string
132
+ /** Override the root `data-mol-id` (defaults to `file-card-${file.id}`). */
133
+ dataMolId?: string
134
+ }
7
135
  ```
8
136
 
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.
137
+ #### `FileIconProps`
138
+
139
+ Props for `<FileIcon>`.
140
+
141
+ ```typescript
142
+ interface FileIconProps {
143
+ /** File kind — picks the SVG glyph. */
144
+ kind: FileKind
145
+ /** Pixel size of the rendered SVG (default 24). */
146
+ size?: number
147
+ /** Optional aria-label. When omitted the icon is `aria-hidden`. */
148
+ ariaLabel?: string
149
+ }
150
+ ```
151
+
152
+ ### Types
153
+
154
+ #### `SizeUnit`
155
+
156
+ The unit token a formatted byte count ends in (`B` plus the binary steps).
157
+
158
+ ```typescript
159
+ type SizeUnit = 'B' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB'
160
+ ```
161
+
162
+ #### `RelativeBucket`
163
+
164
+ A relative-time bucket used to pick a translation key. Higher granularity
165
+ buckets first; falls through to absolute date when older than ~1 year.
166
+
167
+ ```typescript
168
+ type RelativeBucket =
169
+ | { kind: 'just-now' }
170
+ | { kind: 'minutes'; n: number }
171
+ | { kind: 'hours'; n: number }
172
+ | { kind: 'days'; n: number }
173
+ | { kind: 'weeks'; n: number }
174
+ | { kind: 'months'; n: number }
175
+ | { kind: 'absolute'; iso: string }
176
+ ```
177
+
178
+ #### `FileKind`
179
+
180
+ Supported file kinds. Drives icon selection and the "<kind>" portion of
181
+ the aria label translation key (e.g. `file-card.kind.image`).
182
+
183
+ ```typescript
184
+ type FileKind = 'image' | 'video' | 'audio' | 'document' | 'archive' | 'code' | 'folder' | 'other'
185
+ ```
186
+
187
+ ### Classes
188
+
189
+ #### `FileCard`
190
+
191
+ FileCard component.
192
+
193
+ File representation card — icon (or thumbnail), filename, formatted size,
194
+ relative modified date, and an optional trailing actions slot. The host IS
195
+ the root `<div>` (`div[mol-file-card]`), matching React's root exactly.
196
+
197
+ Two layouts:
198
+
199
+ - `'grid'` (default) — square tile with the icon/thumbnail stacked above
200
+ the metadata.
201
+ - `'row'` — horizontal line item with the icon on the left, metadata in
202
+ the middle, and the actions slot on the right.
203
+
204
+ The card's select control: a transparent native button covering the card
205
+ (Enter / Space activate it natively), above the content and below the
206
+ actions slot. A sibling of the actions, not their wrapper, so the action
207
+ buttons stay reachable controls (a button's children are presentational).
208
+ The actions are projected content (`[slot=actions]`); their wrapper
209
+ detaches from the DOM whenever React would not render the region.
210
+
211
+ ```typescript
212
+ @Component({
213
+ selector: 'div[mol-file-card]',
214
+ standalone: true,
215
+ imports: [FileIcon],
216
+ inputs: [
217
+ 'file',
218
+ 'selected',
219
+ 'onClick',
220
+ 'onContextMenu',
221
+ 'layout',
222
+ 'className',
223
+ 'dataMolId',
224
+ 'now',
225
+ ],
226
+ host: {
227
+ '[class]': 'classes()',
228
+ '[attr.role]': '"group"',
229
+ '[attr.aria-label]': 'ariaLabel()',
230
+ '[attr.data-mol-id]': 'rootMolId()',
231
+ '[attr.data-selected]': 'selected ? "true" : null',
232
+ '(contextmenu)': 'handleContextMenu($event)',
233
+ },
234
+ template: `@if (layout === 'row') {<div [class]="iconClasses()" data-mol-id="file-card-icon">@if (file.thumbnail) {<img [src]="file.thumbnail" alt="" [style.width]="'40px'" [style.height]="'40px'" [style.objectFit]="'cover'" [style.borderRadius]="'4px'" />}@else {<svg mol-file-icon [kind]="file.kind" [size]="28" />}</div><div [class]="stackClasses()" [style.flex]="'1'" [style.minWidth]="'0'"><div [class]="nameClasses()" data-mol-id="file-card-name" [style.overflow]="'hidden'" [style.textOverflow]="'ellipsis'" [style.whiteSpace]="'nowrap'">{{ file.name }}</div>@if (hasMeta()) {<div [class]="metaClasses()" data-mol-id="file-card-meta">@if (sizeText()) {<span [attr.aria-label]="sizeLabel()" data-mol-id="file-card-size">{{ sizeText() }}</span>}@if (sizeText() && modifiedText()) {<span aria-hidden="true">·</span>}@if (modifiedText()) {<span [attr.aria-label]="modifiedLabel()" data-mol-id="file-card-modified">{{ modifiedText() }}</span>}</div>}</div>}@else {<div [class]="gridIconClasses()" data-mol-id="file-card-icon" [style.aspectRatio]="'1 / 1'" [style.width]="'100%'">@if (file.thumbnail) {<img [src]="file.thumbnail" alt="" [style.width]="'100%'" [style.height]="'100%'" [style.objectFit]="'cover'" [style.borderRadius]="'4px'" />}@else {<svg mol-file-icon [kind]="file.kind" [size]="48" />}</div><div [class]="nameClasses()" data-mol-id="file-card-name" [style.overflow]="'hidden'" [style.textOverflow]="'ellipsis'" [style.whiteSpace]="'nowrap'">{{ file.name }}</div>@if (hasMeta()) {<div [class]="metaClasses()" data-mol-id="file-card-meta">@if (sizeText()) {<span [attr.aria-label]="sizeLabel()" data-mol-id="file-card-size">{{ sizeText() }}</span>}@if (sizeText() && modifiedText()) {<span aria-hidden="true">·</span>}@if (modifiedText()) {<span [attr.aria-label]="modifiedLabel()" data-mol-id="file-card-modified">{{ modifiedText() }}</span>}</div>}}@if (onClick) {<button type="button" [attr.aria-label]="ariaLabel()" [attr.aria-pressed]="selected ? 'true' : 'false'" data-mol-id="file-card-select" [class]="selectClasses()" [style.background]="'transparent'" [style.border]="'none'" [style.padding]="'0'" (click)="handleClick($event)"></button>}<div [class]="actionsClasses()" data-mol-id="file-card-actions" #actionsSlot><ng-content select="[slot=actions]"></ng-content></div>`,
235
+ })
236
+ export class FileCard implements AfterViewInit, DoCheck {
237
+ file!: FileSummary
238
+ selected?: boolean
239
+ onClick?: (file: FileSummary, event: MouseEvent) => void
240
+ onContextMenu?: (file: FileSummary, event: MouseEvent) => void
241
+ layout?: 'grid' | 'row'
242
+ className?: string
243
+ dataMolId?: string
244
+ now?: Date
245
+
246
+ @ViewChild('actionsSlot') actionsSlot?: ElementRef<HTMLDivElement>
247
+
248
+ private readonly sync = new SlotWrapper(inject(ElementRef), inject(Renderer2))
249
+ private hasActions = false
250
+
251
+ private readonly t: TFn
252
+
253
+ constructor() {
254
+ this.t = useTranslation().t
255
+ }
256
+
257
+ cm(): UIClassMap {
258
+ return getClassMap()
259
+ }
260
+
261
+ classes(): string {
262
+ return this.layout === 'row'
263
+ ? this.cm().cn(
264
+ this.cm().flex({ align: 'center', gap: 'md' }),
265
+ this.cm().sp('p', 2),
266
+ this.onClick ? this.cm().position('relative') : undefined,
267
+ this.className,
268
+ )
269
+ : this.cm().cn(
270
+ this.cm().stack(1),
271
+ this.cm().sp('p', 3),
272
+ this.onClick ? this.cm().position('relative') : undefined,
273
+ this.className,
274
+ )
275
+ }
276
+
277
+ kindLabel(): string {
278
+ switch (this.file.kind) {
279
+ case 'image':
280
+ return this.t('file-card.kind.image', {}, { defaultValue: 'Image file' })
281
+ case 'video':
282
+ return this.t('file-card.kind.video', {}, { defaultValue: 'Video file' })
283
+ case 'audio':
284
+ return this.t('file-card.kind.audio', {}, { defaultValue: 'Audio file' })
285
+ case 'document':
286
+ return this.t('file-card.kind.document', {}, { defaultValue: 'Document' })
287
+ case 'archive':
288
+ return this.t('file-card.kind.archive', {}, { defaultValue: 'Archive' })
289
+ case 'code':
290
+ return this.t('file-card.kind.code', {}, { defaultValue: 'Code file' })
291
+ case 'folder':
292
+ return this.t('file-card.kind.folder', {}, { defaultValue: 'Folder' })
293
+ case 'other':
294
+ return this.t('file-card.kind.other', {}, { defaultValue: 'File' })
295
+ }
296
+ }
297
+
298
+ private sizeUnitText(size: SizeParts): string {
299
+ const t = this.t
300
+ switch (size.unit) {
301
+ case 'B':
302
+ return t('file-card.size.b', { n: size.n }, { defaultValue: '{{n}} B' })
303
+ case 'KB':
304
+ return t('file-card.size.kb', { n: size.n }, { defaultValue: '{{n}} KB' })
305
+ case 'MB':
306
+ return t('file-card.size.mb', { n: size.n }, { defaultValue: '{{n}} MB' })
307
+ case 'GB':
308
+ return t('file-card.size.gb', { n: size.n }, { defaultValue: '{{n}} GB' })
309
+ case 'TB':
310
+ return t('file-card.size.tb', { n: size.n }, { defaultValue: '{{n}} TB' })
311
+ case 'PB':
312
+ return t('file-card.size.pb', { n: size.n }, { defaultValue: '{{n}} PB' })
313
+ }
314
+ }
315
+
316
+ sizeText(): string {
317
+ if (this.file.kind === 'folder') return ''
318
+ return this.sizeUnitText(sizeParts(this.file.size))
319
+ }
320
+
321
+ sizeLabel(): string {
322
+ return this.sizeText()
323
+ ? this.t('file-card.aria.size', { size: this.sizeText() }, { defaultValue: 'Size {{size}}' })
324
+ : ''
325
+ }
326
+
327
+ modifiedText(): string {
328
+ if (!this.file.modifiedAt) return ''
329
+ const at = this.file.modifiedAt
330
+ const t = this.t
331
+ const bucket = relativeBucket(at, this.now)
332
+ switch (bucket.kind) {
333
+ case 'just-now':
334
+ return t('file-card.modified.just-now', {}, { defaultValue: 'just now' })
335
+ case 'minutes':
336
+ return t(
337
+ bucket.n === 1 ? 'file-card.modified.minute-one' : 'file-card.modified.minute-other',
338
+ { count: bucket.n },
339
+ { defaultValue: bucket.n === 1 ? '1 min ago' : `${bucket.n} min ago` },
340
+ )
341
+ case 'hours':
342
+ return t(
343
+ bucket.n === 1 ? 'file-card.modified.hour-one' : 'file-card.modified.hour-other',
344
+ { count: bucket.n },
345
+ { defaultValue: bucket.n === 1 ? '1 hr ago' : `${bucket.n} hr ago` },
346
+ )
347
+ case 'days':
348
+ return t(
349
+ bucket.n === 1 ? 'file-card.modified.day-one' : 'file-card.modified.day-other',
350
+ { count: bucket.n },
351
+ { defaultValue: bucket.n === 1 ? 'yesterday' : `${bucket.n} days ago` },
352
+ )
353
+ case 'weeks':
354
+ return t(
355
+ bucket.n === 1 ? 'file-card.modified.week-one' : 'file-card.modified.week-other',
356
+ { count: bucket.n },
357
+ { defaultValue: bucket.n === 1 ? '1 wk ago' : `${bucket.n} wk ago` },
358
+ )
359
+ case 'months':
360
+ return t(
361
+ bucket.n === 1 ? 'file-card.modified.month-one' : 'file-card.modified.month-other',
362
+ { count: bucket.n },
363
+ { defaultValue: bucket.n === 1 ? '1 mo ago' : `${bucket.n} mo ago` },
364
+ )
365
+ case 'absolute':
366
+ return bucket.iso
367
+ }
368
+ }
369
+
370
+ modifiedLabel(): string {
371
+ return this.modifiedText()
372
+ ? this.t(
373
+ 'file-card.aria.modified',
374
+ { when: this.modifiedText() },
375
+ { defaultValue: 'Modified {{when}}' },
376
+ )
377
+ : ''
378
+ }
379
+
380
+ ariaLabel(): string {
381
+ return this.t(
382
+ 'file-card.aria.root',
383
+ { name: this.file.name, kind: this.kindLabel() },
384
+ { defaultValue: '{{name}}, {{kind}}' },
385
+ )
386
+ }
387
+
388
+ rootMolId(): string {
389
+ return this.dataMolId ?? `file-card-${this.file.id}`
390
+ }
391
+
392
+ hasMeta(): boolean {
393
+ return this.sizeText() !== '' || this.modifiedText() !== ''
394
+ }
395
+ // … truncated — 12 more members: iconClasses, gridIconClasses, stackClasses, nameClasses, metaClasses, selectClasses, actionsClasses, handleClick, handleContextMenu, ngAfterViewInit, ngDoCheck, syncWrappers; the full declaration is in node_modules/@molecule/app-file-card-angular/dist/file-card.component.d.ts
396
+ ```
397
+
398
+ _(Member comments are left out to fit; the full declaration is in `node_modules/@molecule/app-file-card-angular/dist/file-card.component.d.ts`.)_
399
+
400
+ #### `FileIcon`
401
+
402
+ FileIcon component.
403
+
404
+ Icon glyph for a file kind. Stroke-currentColor SVG so it inherits the
405
+ surrounding text color (no ClassMap colors needed). The host IS the `<svg>`
406
+ (`svg[mol-file-icon]`), matching React's root exactly.
407
+
408
+ ```typescript
409
+ @Component({
410
+ selector: 'svg[mol-file-icon]',
411
+ standalone: true,
412
+ inputs: ['kind', 'size', 'ariaLabel'],
413
+ host: {
414
+ '[attr.xmlns]': '"http://www.w3.org/2000/svg"',
415
+ '[attr.width]': 'attrSize()',
416
+ '[attr.height]': 'attrSize()',
417
+ '[attr.viewBox]': '"0 0 24 24"',
418
+ '[attr.fill]': '"none"',
419
+ '[attr.stroke]': '"currentColor"',
420
+ '[attr.stroke-width]': '1.75',
421
+ '[attr.stroke-linecap]': '"round"',
422
+ '[attr.stroke-linejoin]': '"round"',
423
+ '[attr.role]': 'ariaLabel ? "img" : null',
424
+ '[attr.aria-label]': 'ariaLabel ?? null',
425
+ '[attr.aria-hidden]': 'ariaLabel ? null : true',
426
+ '[attr.data-mol-id]': '"file-icon-" + kind',
427
+ },
428
+ // The glyphs are inline in the template, one @case per FileKind, so the
429
+ // rendered elements match React's PATHS exactly (SVG child elements need
430
+ // the svg: namespace prefix under an SVG host).
431
+ // prettier-ignore
432
+ template: `@switch (kind) {
433
+ @case ('image') {<svg:rect x="3" y="5" width="18" height="14" rx="2" /><svg:circle cx="8.5" cy="10.5" r="1.5" /><svg:path d="m21 15-5-5L5 21" />}
434
+ @case ('video') {<svg:rect x="3" y="5" width="18" height="14" rx="2" /><svg:path d="m10 9 5 3-5 3z" fill="currentColor" />}
435
+ @case ('audio') {<svg:path d="M9 18V5l12-2v13" /><svg:circle cx="6" cy="18" r="3" /><svg:circle cx="18" cy="16" r="3" />}
436
+ @case ('document') {<svg:path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z" /><svg:path d="M14 3v6h6" />}
437
+ @case ('archive') {<svg:rect x="3" y="3" width="18" height="6" rx="1" /><svg:path d="M3 9v10a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V9" /><svg:path d="M10 13h4" />}
438
+ @case ('code') {<svg:path d="m9 8-5 4 5 4" /><svg:path d="m15 8 5 4-5 4" /><svg:path d="m13 5-2 14" />}
439
+ @case ('folder') {<svg:path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />}
440
+ @case ('other') {<svg:path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z" /><svg:path d="M14 3v6h6" /><svg:path d="M9 14h6" /><svg:path d="M9 17h4" />}
441
+ }`,
442
+ })
443
+ export class FileIcon {
444
+ /** File kind — picks the SVG glyph. */
445
+ kind!: FileKind
446
+ /** Pixel size of the rendered SVG (default 24). */
447
+ size?: number
448
+ /** Optional aria-label. When omitted the icon is `aria-hidden`. */
449
+ ariaLabel?: string
450
+
451
+ /**
452
+ * The rendered size (React's `size = 24` default parameter: a later-bound
453
+ * write of `undefined` must not erase the default).
454
+ * @returns The pixel size.
455
+ */
456
+ attrSize(): number {
457
+ return this.size ?? 24
458
+ }
459
+ }
460
+ ```
461
+
462
+ ### Functions
463
+
464
+ #### `sizeParts(value)`
465
+
466
+ Split a non-negative byte count into its displayed number and unit token
467
+ (e.g. `420` + `B`, `1.4` + `KB`, `471` + `MB`) — the two halves
468
+ {@link bytes} joins, exposed so the card can translate the unit word via
469
+ `t()` (one literal key per {@link SizeUnit}, as the kind labels do).
470
+
471
+ Uses a 1024 base (binary) and 1 fractional digit for KB+. Returns the
472
+ `0 B` parts for non-finite or negative inputs so callers do not need to
473
+ pre-validate.
474
+
475
+ ```typescript
476
+ function sizeParts(value: number): SizeParts
477
+ ```
478
+
479
+ - `value` — Byte count (>= 0).
480
+
481
+ **Returns:** The displayed number and unit token.
482
+
483
+ #### `bytes(value)`
484
+
485
+ Format a non-negative byte count as a short human-readable string
486
+ (e.g. `420 B`, `1.4 KB`, `2.3 MB`, `4.7 GB`, `8.1 TB`).
487
+
488
+ The unlocalized join of {@link sizeParts}'s two halves, for callers that
489
+ want the raw SI shorthand. The card itself renders the unit through `t()`
490
+ (`file-card.size.<unit>` keys in the locale bond) so a locale switch
491
+ translates it; the unit token is universal SI shorthand — a language that
492
+ names bytes differently (French octets, Russian КБ) changes only the token,
493
+ never the magnitude.
494
+
495
+ ```typescript
496
+ function bytes(value: number): string
497
+ ```
498
+
499
+ - `value` — Byte count (>= 0).
500
+
501
+ **Returns:** Formatted size string.
502
+
503
+ #### `relativeBucket(at, now)`
504
+
505
+ Bucket a `Date` (or ISO string / ms timestamp) against `now` into a
506
+ relative-time bucket. The bucket is purely structural — translation keys
507
+ and pluralization are applied by the consumer.
508
+
509
+ ```typescript
510
+ function relativeBucket(at: string | number | Date, now?: Date): RelativeBucket
511
+ ```
512
+
513
+ - `at` — Modified-at timestamp (ISO string, ms epoch, or `Date`).
514
+ - `now` — Reference "now" (defaults to `new Date()`). Injected for tests.
515
+
516
+ **Returns:** A `RelativeBucket` describing the offset from `now`.
517
+
518
+ ## Injection Notes
519
+
520
+ ### Requirements
521
+
522
+ Peer dependencies:
523
+
524
+ - `@angular/common` ^22.0.0
525
+ - `@angular/core` ^22.0.0
526
+ - `@angular/platform-browser` ^22.0.0
527
+ - `@molecule/app-angular` ^3.5.0
528
+ - `@molecule/app-ui` ^1.0.1
529
+ - `@molecule/app-ui-angular` ^1.1.0
530
+
531
+ ### Runtime Dependencies
532
+
533
+ - `@angular/common`
534
+ - `@angular/core`
535
+ - `@angular/platform-browser`
536
+ - `@molecule/app-angular`
537
+ - `@molecule/app-ui`
538
+ - `@molecule/app-ui-angular`
539
+
540
+ - All styling routes through `getClassMap()` from `@molecule/app-ui` —
541
+ swap the ClassMap bond to restyle without touching this package.
542
+ - All user-visible text routes through `t()` (via `@molecule/app-angular`'s
543
+ `useTranslation`) and translates via the companion
544
+ `@molecule/app-locales-file-card` locale bond. English fallbacks are
545
+ inlined so the card works without the locale bond present.
546
+ - Node props are projected content: `actions` is selected by
547
+ `[slot=actions]`, everything else lands in the card body as the default
548
+ projection.
549
+
550
+ ## Translations
10
551
 
11
- License: Apache-2.0
552
+ 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-angular",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Angular file card primitives — icon, name, size, modified date, actions; grid + row layouts",
5
5
  "homepage": "https://www.molecule.dev/packages/app-file-card-angular",
6
6
  "type": "module",
@@ -57,12 +57,12 @@
57
57
  "@angular/compiler-cli": "22.2.3",
58
58
  "@angular/core": "22.2.3",
59
59
  "@angular/platform-browser": "22.2.3",
60
- "@molecule/app-angular": "3.7.2",
60
+ "@molecule/app-angular": "3.9.0",
61
61
  "@molecule/app-framework-conformance": "0.0.0",
62
62
  "@molecule/app-i18n": "1.2.2",
63
63
  "@molecule/app-icons": "1.0.4",
64
- "@molecule/app-ui": "1.4.0",
65
- "@molecule/app-ui-angular": "1.2.1",
64
+ "@molecule/app-ui": "1.5.0",
65
+ "@molecule/app-ui-angular": "1.3.1",
66
66
  "@types/node": "26.6.5",
67
67
  "jsdom": "30.1.3",
68
68
  "rxjs": "7.8.2",