@atom63/widgets 0.1.0-beta.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.
@@ -0,0 +1,714 @@
1
+ import { DestinationKind } from '@atom63/ui-react';
2
+ import * as React from 'react';
3
+ import { CSSProperties, ComponentPropsWithRef, ReactNode, ComponentType, AnchorHTMLAttributes } from 'react';
4
+ import { W as WidgetSize } from './types-C0zDKyo1.js';
5
+
6
+ interface WidgetDestination {
7
+ /** Where it goes, from the widget's own runtime origin. */
8
+ kind: DestinationKind;
9
+ /**
10
+ * The href to actually render.
11
+ *
12
+ * For `internal` this is origin-relative (`/projects/x?a=1#b`) even when the
13
+ * card authored an absolute URL, because that is what a router can route.
14
+ * For `external` it is the href as authored.
15
+ */
16
+ href: string;
17
+ }
18
+ /**
19
+ * Resolve an `href` into the destination a widget should render.
20
+ *
21
+ * This has to happen at render, not in data: portfolio cards carry absolute
22
+ * `https://atom63.io/...` hrefs, which are an in-app route on atom63.io and a
23
+ * cross-origin link from os.atom63.io. The same card is genuinely both, so a
24
+ * `kind` baked into the card would be wrong in one host.
25
+ *
26
+ * Normalising the href is the other half of that, and skipping it fails
27
+ * silently rather than visibly: an absolute same-origin URL still points at the
28
+ * right page, so the indicator looks correct and the anchor still works — but
29
+ * every router-level behaviour is lost. On atom63.io, `DetailHrefLink` rejects
30
+ * anything not starting with `/` and falls back to a plain navigation, so the
31
+ * card reloads the whole site instead of opening the project overlay. Handing
32
+ * back the path is what lets a host route it.
33
+ *
34
+ * `mailto:` / `tel:` / `sms:` are neither kind: they leave the web entirely and
35
+ * neither icon describes that. Callers get `null` and should render no
36
+ * indicator rather than guess.
37
+ *
38
+ * Off-origin during SSR is treated as external, matching `isExternalMdxHref` —
39
+ * an absolute http(s) URL with no origin to compare against is the case where
40
+ * assuming in-app navigation would break the link.
41
+ */
42
+ declare function resolveDestination(href: string | undefined,
43
+ /**
44
+ * Extra origins the running app answers for.
45
+ *
46
+ * The running origin alone is right in production and wrong everywhere a
47
+ * change is tested: atom63.io's own cards author absolute
48
+ * `https://atom63.io/...` hrefs, which compare as cross-origin on
49
+ * `localhost` and on preview deployments. Prefer `useWidgetDestination`,
50
+ * which reads these from the host.
51
+ */
52
+ appOrigins?: readonly string[]): WidgetDestination | null;
53
+ /** Just the kind, when the caller does not need the normalised href. */
54
+ declare function resolveDestinationKind(href: string | undefined, appOrigins?: readonly string[]): DestinationKind | null;
55
+
56
+ type WidgetImageAspect = '1/1' | '16/9' | '2/3' | 'none';
57
+ interface WidgetImageProps {
58
+ alt: string;
59
+ aspectRatio?: WidgetImageAspect;
60
+ className?: string;
61
+ containerClassName?: string;
62
+ /**
63
+ * Crossfade when `src` swaps after the first painted frame (shuffle / fan tiles).
64
+ * First paint still mounts immediately; only later swaps wait on decode.
65
+ */
66
+ crossfade?: boolean;
67
+ /** Prefer eager decode for above-the-fold / widget tiles that swap on shuffle. */
68
+ priority?: boolean;
69
+ /**
70
+ * Callback with the painted element, for canvas work that needs pixels —
71
+ * dominant-color extraction, for instance.
72
+ *
73
+ * This is the element already on screen, so sampling it issues no second
74
+ * request and composes with lazy loading. Prefer it over re-fetching the URL
75
+ * (`useExtractColor`), which pulls every full-size source in a lazy grid.
76
+ * Cross-origin sources are loaded without `crossOrigin`, so sampling one
77
+ * taints the canvas and the extractor reports no colour rather than throwing.
78
+ */
79
+ onLoadedImage?: (image: HTMLImageElement) => void;
80
+ showSkeleton?: boolean;
81
+ src?: string;
82
+ }
83
+ /**
84
+ * The aspect ratio is a `data-aspect` attribute that the stylesheet maps to
85
+ * `aspect-ratio` (`none` sets none), so a consumer class can still override it.
86
+ */
87
+ declare function WidgetImage({ alt, aspectRatio, className, containerClassName, crossfade, onLoadedImage, priority, showSkeleton, src, }: WidgetImageProps): React.JSX.Element;
88
+
89
+ /** Span of a widget in widget units (one unit = one cell of the host grid). */
90
+ interface WidgetUnitSpan {
91
+ cols: number;
92
+ rows: number;
93
+ }
94
+ /**
95
+ * Single source of truth for widget geometry.
96
+ *
97
+ * Hosts map a widget unit onto their own grid:
98
+ * - os63 desktop: 1 widget unit = 2 desktop cells
99
+ * - atom63.io web: 1 widget unit = 1 CSS grid column
100
+ */
101
+ declare const WIDGET_UNIT_SPAN: Record<WidgetSize, WidgetUnitSpan>;
102
+ /**
103
+ * Internal authoring coordinate width for one widget unit.
104
+ *
105
+ * Existing widget values are authored on this coordinate system. Presentation
106
+ * scale is measured against WIDGET_CANONICAL_CELL_PX instead.
107
+ */
108
+ declare const WIDGET_UNIT_BASE_PX = 256;
109
+ /** OS63-sized 100% presentation width of one widget cell, in CSS px. */
110
+ declare const WIDGET_CANONICAL_CELL_PX = 188;
111
+ /** Largest supported proportional presentation scale above the canonical cell. */
112
+ declare const WIDGET_MAX_PRESENTATION_SCALE = 1.375;
113
+ /**
114
+ * Minimum font size per floor bucket on the canonical presentation canvas.
115
+ * Whole-canvas presentation scaling preserves these proportions in smaller
116
+ * hosts rather than reflowing around a fixed physical type floor.
117
+ *
118
+ * Intent roles (chrome / label / body / title / …) live in `WIDGET_TYPE_RAMP`
119
+ * and map onto these buckets via `WIDGET_TYPE_ROLE_FLOOR`.
120
+ *
121
+ * `display` is deliberately unfloored: a 40px figure at 24px is still legible,
122
+ * and flooring it would distort the composition it anchors.
123
+ */
124
+ declare const WIDGET_TYPE_FLOOR: {
125
+ readonly label: 11;
126
+ readonly body: 12;
127
+ readonly display: 0;
128
+ };
129
+ /** Floor buckets used by the type ramp. Prefer `WidgetTypeRampRole` for authoring. */
130
+ type WidgetTypeFloorRole = keyof typeof WIDGET_TYPE_FLOOR;
131
+ /** @deprecated Use `WidgetTypeFloorRole` or `WidgetTypeRampRole`. */
132
+ type WidgetTypeRole = WidgetTypeFloorRole;
133
+
134
+ /** Optical density presets — multiply `--widget-scale`. */
135
+ declare const WIDGET_DENSITY_SCALE: {
136
+ readonly compact: 0.9;
137
+ readonly default: 1;
138
+ readonly comfortable: 1.1;
139
+ };
140
+ type WidgetDensity = keyof typeof WIDGET_DENSITY_SCALE;
141
+ interface WidgetSizeStyleOptions {
142
+ /** Extra multiplier on `--widget-u`. @default 1 */
143
+ scale?: number;
144
+ /** Named density preset; multiplies `scale`. @default 'default' */
145
+ density?: WidgetDensity;
146
+ /**
147
+ * Floor for `--widget-u` in CSS px. Unset by default — legibility is
148
+ * protected by per-role type floors, not by arresting the unit. A unit
149
+ * floor lets content outgrow its own tile and overflow.
150
+ */
151
+ minScale?: number;
152
+ }
153
+ type WidgetSizeStyle = CSSProperties & {
154
+ '--a63-control-min-target': string;
155
+ '--a63-control-min-target-lg': string;
156
+ '--a63-control-min-target-xl': string;
157
+ '--widget-cell': string;
158
+ '--widget-raw-u': string;
159
+ '--widget-rows': string;
160
+ '--widget-scale': string;
161
+ '--widget-span': string;
162
+ '--widget-u': string;
163
+ };
164
+ /** The design-unit properties alone — no span, no grid placement. */
165
+ type WidgetUnitStyle = CSSProperties & {
166
+ '--a63-control-min-target': string;
167
+ '--a63-control-min-target-lg': string;
168
+ '--a63-control-min-target-xl': string;
169
+ '--widget-cell': string;
170
+ '--widget-raw-u': string;
171
+ '--widget-scale': string;
172
+ '--widget-u': string;
173
+ };
174
+ type WidgetPresentationStyle = CSSProperties & {
175
+ '--a63-control-min-target': string;
176
+ '--a63-control-min-target-lg': string;
177
+ '--a63-control-min-target-xl': string;
178
+ '--widget-interaction-target': string;
179
+ '--widget-presentation-scale': string;
180
+ '--widget-u': string;
181
+ };
182
+ /**
183
+ * Design-unit properties for a host whose cell width is **known in px** — the
184
+ * os63 desktop, whose tiles are laid out on a fixed grid rather than inside a
185
+ * `WidgetGrid` container.
186
+ *
187
+ * `widgetSizeStyle()` cannot serve that host: its cell is `100cqi`-derived, so
188
+ * with no `@container` ancestor it silently resolves against the VIEWPORT, and
189
+ * its `gridColumn`/`gridRow` would fight the desktop's own placement. This
190
+ * returns the unit properties only, so content authored in `wuStyle` renders in
191
+ * both hosts instead of collapsing to dropped `calc()` declarations in one.
192
+ */
193
+ declare function widgetUnitStyle(cellPx: number, { density, minScale, scale }?: WidgetSizeStyleOptions): WidgetUnitStyle;
194
+ /**
195
+ * Normalize a widget back to its canonical 188px composition, then transform
196
+ * the complete canvas to the host cell. This catches fixed rem/Tailwind values
197
+ * as well as design-unit values, preserving the original spacing and type
198
+ * ratios both above and below the canonical size. A transform is used instead
199
+ * of CSS zoom so the presentation contract behaves consistently in Firefox.
200
+ */
201
+ declare function widgetPresentationStyle(cellPx?: number): WidgetPresentationStyle;
202
+ /**
203
+ * Build the geometry and design-unit custom properties for a widget size.
204
+ *
205
+ * The unit divides by the span, so a `medium` tile is twice as wide yet resolves
206
+ * the same `--widget-u` as a `small` — type and padding stay constant across
207
+ * sizes, and only the composition gains room.
208
+ */
209
+ declare function widgetSizeStyle(size: WidgetSize, { density, minScale, scale }?: WidgetSizeStyleOptions): WidgetSizeStyle;
210
+
211
+ /**
212
+ * Inline-style helpers for authoring widget content in DESIGN px against
213
+ * `--widget-u`, the design unit `widgetSizeStyle()` publishes on every tile.
214
+ *
215
+ * These live here because the package owns `--widget-u`; a host defining its
216
+ * own readers for a package-owned custom property is the inversion this fixes.
217
+ * Prefer them over Tailwind arbitrary classes: dynamic class strings are never
218
+ * seen by the Tailwind scanner.
219
+ *
220
+ * ## What design px does NOT do
221
+ *
222
+ * It does not make a value "scale with the tile" where a fixed rem or px value
223
+ * would not. `WidgetViewport` wraps every widget in a transform-scaled canvas
224
+ * (`widgetPresentationStyle`), and a transform scales the whole composition —
225
+ * fixed rem, fixed px and design-unit lengths alike. A `2.4rem` box measured
226
+ * 38.4px at the canonical cell and 52.7px at a 1.372 host, exactly like a
227
+ * `wu()` length would.
228
+ *
229
+ * So the reason to author in design px is CONSISTENCY, not scaling: the type
230
+ * ramp, the insets and the gaps all live on the same 256 canvas, so one dial
231
+ * moves the whole composition and no value has to be converted by hand. Do not
232
+ * justify a conversion as a rendering fix — it will not change the render, and
233
+ * a changeset that claims it did is wrong.
234
+ */
235
+ /**
236
+ * Length from a design-px value.
237
+ * Use in inline `style` (not Tailwind class strings — scanners never see dynamic classes).
238
+ *
239
+ * Falls back to `1px` — design px == CSS px — when no host published a unit.
240
+ * Without the fallback the `calc()` is INVALID and the browser drops the whole
241
+ * declaration, so a widget in an unpublishing host loses every padding, gap and
242
+ * font size at once and renders as unstyled text. That is a silent, total
243
+ * collapse that types, tests and lint cannot see. Degrading to design px keeps
244
+ * the widget legible; hosts that publish a cell-derived unit still override it.
245
+ *
246
+ * @example style={{ padding: wu(16), gap: wu(12) }}
247
+ */
248
+ declare function wu(designPx: number): string;
249
+ /**
250
+ * Proportional length with optional a11y floor / ceiling in CSS px.
251
+ */
252
+ declare function wuClamp(designPx: number, minPx?: number, maxPx?: number): string;
253
+ type Style = CSSProperties;
254
+ /**
255
+ * Inline-style helpers for design-px space / type / size.
256
+ *
257
+ * Prefer these over Tailwind arbitrary classes — dynamic class strings are not
258
+ * detected by the Tailwind scanner.
259
+ */
260
+ declare const wuStyle: {
261
+ readonly p: (n: number) => Style;
262
+ readonly px: (n: number) => Style;
263
+ readonly py: (n: number) => Style;
264
+ readonly pt: (n: number) => Style;
265
+ readonly pb: (n: number) => Style;
266
+ readonly gap: (n: number) => Style;
267
+ readonly gapX: (n: number) => Style;
268
+ readonly gapY: (n: number) => Style;
269
+ readonly m: (n: number) => Style;
270
+ readonly mt: (n: number) => Style;
271
+ readonly mb: (n: number) => Style;
272
+ readonly ml: (n: number) => Style;
273
+ readonly mr: (n: number) => Style;
274
+ readonly mx: (n: number) => Style;
275
+ readonly my: (n: number) => Style;
276
+ readonly size: (n: number) => Style;
277
+ readonly h: (n: number) => Style;
278
+ readonly w: (n: number) => Style;
279
+ readonly text: (n: number) => Style;
280
+ readonly textMin: (n: number, minPx: number) => Style;
281
+ readonly rounded: (n: number) => Style;
282
+ };
283
+ /** Merge style objects (later wins). */
284
+ declare function wuMerge(...parts: Array<Style | undefined | null | false>): Style;
285
+
286
+ /**
287
+ * Shared body / face inset in design-px (256 authoring canvas).
288
+ *
289
+ * Calibrated so the OS63 188 cell resolves ≈ prior Tailwind `px-3` / `px-4`:
290
+ * - 16 × 188/256 ≈ 11.75px (was `px-3`)
291
+ * - 22 × 188/256 ≈ 16.1px (was `px-4`)
292
+ *
293
+ * Prefer `widgetInsetStyle` over local `wuStyle.p(…)` or `px-3` / `p-3.5`.
294
+ */
295
+ declare const WIDGET_BODY_INSET: {
296
+ readonly small: 16;
297
+ readonly medium: 22;
298
+ readonly large: 22;
299
+ };
300
+ /**
301
+ * Shared stack gap in design-px between body children.
302
+ * ≈ Tailwind `gap-2` / `gap-3` at the OS63 cell.
303
+ */
304
+ declare const WIDGET_BODY_GAP: {
305
+ readonly small: 11;
306
+ readonly medium: 11;
307
+ readonly large: 16;
308
+ };
309
+ type WidgetInsetMode =
310
+ /** Full-face chrome-less body — padding on all sides. */
311
+ 'face'
312
+ /**
313
+ * Horizontal + bottom only. Used under `WidgetCardHeader`, and for
314
+ * chrome-less faces with intentional top bleed (e.g. Behance ribbons).
315
+ */
316
+ | 'body';
317
+ interface WidgetInsetStyleOptions {
318
+ /** Include `gap` from `WIDGET_BODY_GAP`. Default true. */
319
+ gap?: boolean;
320
+ }
321
+ /** Design-px inset for a footprint. */
322
+ declare function widgetInsetPx(size: WidgetSize): number;
323
+ /**
324
+ * Inline padding (+ optional gap) from the shared inset ramp.
325
+ *
326
+ * @example
327
+ * // Chrome-less Behance / Instagram / Location / Weather
328
+ * style={widgetInsetStyle(size, 'face')}
329
+ *
330
+ * // Under WidgetCardHeader (GitHub, Profile, …)
331
+ * style={widgetInsetStyle(size, 'body')}
332
+ */
333
+ declare function widgetInsetStyle(size: WidgetSize, mode?: WidgetInsetMode, options?: WidgetInsetStyleOptions): CSSProperties;
334
+
335
+ /**
336
+ * Intent roles for widget content type.
337
+ *
338
+ * Floors live on three buckets (`label` / `body` / `display`). Ramp roles map
339
+ * onto those buckets so authors pick meaning, not raw px.
340
+ *
341
+ * Design-px targets are authored against `--widget-u` (256 design canvas).
342
+ * Footprint steps (`small` / `medium` / `large`) are hand-authored growth for
343
+ * roles that earn more room — they are not automatic scale-with-box.
344
+ */
345
+ declare const WIDGET_TYPE_ROLE_FLOOR: {
346
+ /** Quiet uppercase identity on the chrome header. */
347
+ readonly chrome: "label";
348
+ /** Smallest supporting labels (stat keys, legends, zone tags). */
349
+ readonly label: "label";
350
+ /** Default reading copy. */
351
+ readonly body: "body";
352
+ /** Compact identity (handles, short names). */
353
+ readonly name: "body";
354
+ /** Content headings that are not the hero figure. */
355
+ readonly title: "body";
356
+ /** Featured content name (project title, primary listing). */
357
+ readonly headline: "body";
358
+ /** Mid-weight digital / tabular figures (profile stats). */
359
+ readonly stat: "body";
360
+ /** Hero figures — temperature, big totals. Unfloored. */
361
+ readonly display: "display";
362
+ /** Dense hero digits (clock faces beside a second column). Unfloored. */
363
+ readonly displayCompact: "display";
364
+ };
365
+ type WidgetTypeRampRole = keyof typeof WIDGET_TYPE_ROLE_FLOOR;
366
+ /**
367
+ * Derived from the live widget inventory (Location place/temp/clock, Behance
368
+ * stats, Open Source title, Instagram handle, WidgetCardTitle chrome).
369
+ * Prefer `widgetTypeStyle(role, size)` over local SIZE maps or Tailwind
370
+ * `text-*` for content type.
371
+ *
372
+ * ## Read this before changing a design-px value
373
+ *
374
+ * `--widget-u` is ALWAYS `188 / 256` ≈ `0.734`, at every host and every cell
375
+ * size. `widgetPresentationStyle` divides the unit back out of the presentation
376
+ * transform, so one canonical composition is scaled as a whole canvas rather
377
+ * than re-resolved per cell. A design-px value therefore renders at
378
+ * `design × 0.734` — the 256 canvas never renders 1:1.
379
+ *
380
+ * That makes the CSS-px floors (`WIDGET_TYPE_FLOOR`) load-bearing rather than a
381
+ * rare safety net, and the ramp was previously authored as if they were rare:
382
+ * `label` (10), `body` (13), `name` (14) and `title` (16) all resolved BELOW
383
+ * their floor and rendered at a single 11–12px step, so four distinct roles
384
+ * were separated only by weight and colour, and the authored headline-to-body
385
+ * ratio of 1.69 rendered as 1.35. `chrome` even inverted — authored larger than
386
+ * `label`, rendered smaller, because its `floorPx` override let it through.
387
+ *
388
+ * The content roles are now authored so `design × 0.734` clears the floor on
389
+ * its own and lands on a deliberate rendered ladder at the 1×1 footprint:
390
+ *
391
+ * | role | design | renders |
392
+ * | -------- | ------ | ------- |
393
+ * | chrome | 14 | 10.3 |
394
+ * | label | 15 | 11.0 |
395
+ * | body | 17 | 12.5 |
396
+ * | name | 18 | 13.2 |
397
+ * | title | 20 | 14.7 |
398
+ * | stat | 22 | 16.2 |
399
+ * | headline | 26 | 19.1 |
400
+ * | display | 48 | 35.3 |
401
+ *
402
+ * `display` / `displayCompact` are unchanged: they never floored, so their
403
+ * rendered figures were already the calibrated ones.
404
+ *
405
+ * ## The footprint columns are a curve, not three free values
406
+ *
407
+ * `body` is deliberately FLAT at 17 across all three footprints: it is reading
408
+ * copy, and a widget that changes its reading size when the tile grows is
409
+ * harder to scan across a desktop, not easier. A wider tile buys measure and
410
+ * room, not bigger prose.
411
+ *
412
+ * That makes every heading role's footprint column a RATIO against a fixed
413
+ * body, and the previous values let the top of the ramp run away from the
414
+ * bottom exactly where there is most type on screen:
415
+ *
416
+ * | role | small | medium | large | old title:body |
417
+ * | -------- | ----- | ------ | ----- | -------------- |
418
+ * | title | 20 | 23 | 30 | 1.18 → 1.76 |
419
+ * | stat | 22 | 24 | 29 | |
420
+ * | headline | 26 | 26 | 34 | |
421
+ *
422
+ * A 1.18 step at 1×1 and a 1.76 step at 2×2 are not one hierarchy, they are two
423
+ * — and the 2×2 one shouts, which is the whole "widget type feels too big"
424
+ * complaint. `headline` was also non-monotonic (26 at both small and medium,
425
+ * then a jump to 34), so doubling the tile width bought the hero name nothing
426
+ * and doubling it again bought it 31%.
427
+ *
428
+ * `name` (18 / 19 / 22) was already the disciplined curve — roughly ×1.06 and
429
+ * ×1.22 off its 1×1 value — so the other heading roles now follow it. The 1×1
430
+ * column is untouched: that ladder is the calibrated one above, and the defect
431
+ * was never there.
432
+ *
433
+ * | role | small | medium | large | title:body |
434
+ * | -------- | ----- | ------ | ----- | ------------ |
435
+ * | title | 20 | 22 | 24 | 1.18 → 1.41 |
436
+ * | stat | 22 | 23 | 26 | |
437
+ * | headline | 26 | 28 | 32 | |
438
+ *
439
+ * When adding a footprint step, move along this curve. A role that needs a
440
+ * bigger jump than the curve gives is usually the wrong role for the job.
441
+ */
442
+ declare const WIDGET_TYPE_RAMP: {
443
+ readonly chrome: {
444
+ readonly designPx: 14;
445
+ readonly weight: 500;
446
+ readonly trackingEm: 0.025;
447
+ readonly transform: "uppercase";
448
+ readonly leading: 1;
449
+ readonly floorPx: 10;
450
+ readonly iconDesignPx: 14;
451
+ readonly iconFloorPx: 11;
452
+ };
453
+ readonly label: {
454
+ readonly designPx: 15;
455
+ readonly weight: 500;
456
+ };
457
+ readonly body: {
458
+ readonly designPx: 17;
459
+ readonly weight: 400;
460
+ };
461
+ readonly name: {
462
+ readonly designPx: {
463
+ readonly small: 18;
464
+ readonly medium: 19;
465
+ readonly large: 22;
466
+ };
467
+ readonly weight: 600;
468
+ };
469
+ readonly title: {
470
+ readonly designPx: {
471
+ readonly small: 20;
472
+ readonly medium: 22;
473
+ readonly large: 24;
474
+ };
475
+ readonly weight: 600;
476
+ };
477
+ readonly headline: {
478
+ readonly designPx: {
479
+ readonly small: 26;
480
+ readonly medium: 28;
481
+ readonly large: 32;
482
+ };
483
+ readonly weight: 600;
484
+ readonly leading: 1.18;
485
+ };
486
+ readonly stat: {
487
+ readonly designPx: {
488
+ readonly small: 22;
489
+ readonly medium: 23;
490
+ readonly large: 26;
491
+ };
492
+ readonly weight: 600;
493
+ };
494
+ readonly display: {
495
+ readonly designPx: {
496
+ readonly small: 48;
497
+ readonly medium: 44;
498
+ readonly large: 64;
499
+ };
500
+ readonly weight: 600;
501
+ };
502
+ readonly displayCompact: {
503
+ readonly designPx: {
504
+ readonly small: 40;
505
+ readonly medium: 34;
506
+ readonly large: 52;
507
+ };
508
+ readonly weight: 600;
509
+ };
510
+ };
511
+ interface WidgetTypeStyleOptions {
512
+ /** Override design-px when a composition needs a one-off step. Prefer ramp. */
513
+ designPx?: number;
514
+ /** Override weight (e.g. weather display uses extralight). */
515
+ weight?: number;
516
+ leading?: number;
517
+ trackingEm?: number;
518
+ }
519
+ /** Design-px target for a ramp role at a footprint. */
520
+ declare function widgetTypeDesignPx(role: WidgetTypeRampRole, size?: WidgetSize): number;
521
+ /**
522
+ * Inline type styles for a ramp role.
523
+ *
524
+ * Returns `fontSize` (wu + floor), `fontWeight`, and chrome extras when present.
525
+ * Pair with Tailwind only for color / truncation / layout — not for size.
526
+ */
527
+ declare function widgetTypeStyle(role: WidgetTypeRampRole, size?: WidgetSize, options?: WidgetTypeStyleOptions): CSSProperties;
528
+ /**
529
+ * Leading icon box for `WidgetCardTitle` — sized from the chrome recipe so the
530
+ * glyph tracks the quiet header label.
531
+ */
532
+ declare function widgetChromeIconStyle(): CSSProperties;
533
+ /**
534
+ * Descender relief for text that also carries `line-clamp-*`.
535
+ *
536
+ * `line-clamp` implies `overflow: hidden`, and the clip box is exactly
537
+ * `line-height × lines`. Any ramp role authored with tight leading therefore
538
+ * has a line box SHORTER than the font's own box, and the last line's
539
+ * descenders are shaved — silently, at every width, whether or not the clamp
540
+ * actually truncates anything.
541
+ *
542
+ * Measured on the open-source headline (Hedvig Letters Serif 600, leading
543
+ * 1.12): the box ended 1.95px above the ink. `0.24em` covers the font's full
544
+ * declared descent rather than one sample string, so no glyph can reach past
545
+ * it, and the matching negative margin hands the space back to layout — the
546
+ * glyphs become whole without anything moving.
547
+ *
548
+ * `truncate` has the same problem for the same reason — it also sets
549
+ * `overflow: hidden`, and a single line box is just as short.
550
+ *
551
+ * Pass `'emoji'` for a line that can carry one. Emoji ink runs well past the
552
+ * font's declared descent, so the text relief only halves the cut: the profile
553
+ * stat row still shaved 3px off a cat's chin at `leading: 1`.
554
+ *
555
+ * @example
556
+ * <span className="line-clamp-4" style={widgetClampRelief()}>{title}</span>
557
+ * <dt className="truncate" style={widgetClampRelief('emoji')}>{label}</dt>
558
+ */
559
+ declare function widgetClampRelief(content?: 'emoji' | 'text'): CSSProperties;
560
+
561
+ /**
562
+ * Reports the size a widget is being rendered at, so a widget supporting more
563
+ * than one size can pick the matching composition.
564
+ */
565
+ declare function useWidgetSize(): WidgetSize;
566
+ interface WidgetSizeProviderProps {
567
+ children: ReactNode;
568
+ size: WidgetSize;
569
+ }
570
+ declare function WidgetSizeProvider({ children, size }: WidgetSizeProviderProps): React.JSX.Element;
571
+ interface WidgetGridProps extends ComponentPropsWithRef<'div'> {
572
+ /** Track count. Fixed, not responsive — every size keeps its shape at every width. @default 2 */
573
+ columns?: number;
574
+ /** Gutter in CSS px. @default 12 */
575
+ gap?: number;
576
+ }
577
+ /**
578
+ * Widget grid container. Owns track count and gap, and publishes both as custom
579
+ * properties so each tile's cell-derived unit can divide them out.
580
+ *
581
+ * Tracks are explicit rather than `auto-fill`: with intrinsic tracks a narrow
582
+ * container resolves to one column and a `span 2` tile would create an implicit
583
+ * second column and overflow.
584
+ *
585
+ * Rows are sized here rather than on the tile: an element cannot resolve
586
+ * container-query units against the `@container` it establishes itself, so the
587
+ * grid is wrapped in a container and `grid-auto-rows` resolves `100cqi` against
588
+ * that ancestor. Tiles just fill their area, and spanning tiles inherit the
589
+ * inter-row gaps from the grid.
590
+ */
591
+ declare function WidgetGrid({ children, columns, gap, ref, style, ...props }: WidgetGridProps): React.JSX.Element;
592
+
593
+ interface WidgetViewportProps extends Omit<ComponentPropsWithRef<'article'>, 'children'> {
594
+ /**
595
+ * The host grid's cell width in CSS px, when the host already knows it.
596
+ *
597
+ * Left unset the viewport derives the cell from its own measured box, which
598
+ * is right at rest and wrong while that box is moving: a host that animates
599
+ * the shell between two sizes re-fires the observer every frame, the cell
600
+ * follows the travelling width, and the composition zooms inside the growing
601
+ * box instead of reflowing in it. The cell a tile lands in is a property of
602
+ * the *grid*, identical for a 1x1 and a 2x1, so a host that measures its own
603
+ * tracks can say so once and the observer never runs.
604
+ *
605
+ * Passing it also frees the canvas height to follow the host box rather than
606
+ * the cell — the two are the same number at rest, and only the first of them
607
+ * is still true mid-flight.
608
+ */
609
+ cellPx?: number;
610
+ children: ReactNode;
611
+ size: WidgetSize;
612
+ }
613
+ /**
614
+ * Fluid host boundary for a canonical widget view.
615
+ *
616
+ * The viewport owns grid placement and publishes the design unit. The widget
617
+ * view inside owns all visible surface, composition, and state styling.
618
+ */
619
+ declare function WidgetViewport({ cellPx, children, className, ref, size, style, ...props }: WidgetViewportProps): React.JSX.Element;
620
+ /**
621
+ * Wrap a sized widget component so it carries its own viewport.
622
+ *
623
+ * A widget's composition is authored on a 256 design-px canvas and only
624
+ * resolves against real pixels once a host publishes `--widget-u`. Grid hosts
625
+ * (the OS63 desktop, the atom63.io board) publish it by placing tiles in a
626
+ * `WidgetViewport` themselves. Hosts that render a widget on its own — agent
627
+ * chat renders one per message, in an intrinsically sized frame — have no grid
628
+ * to hang that on, and a widget mounted without it silently renders design px
629
+ * at 1:1: ~36% oversized type, padding and gaps, clipped by the shell wherever
630
+ * the overflow lands.
631
+ *
632
+ * Use this at the registry boundary of such a host so the widget arrives
633
+ * already scaled, rather than re-deriving the unit per call site.
634
+ *
635
+ * @example
636
+ * component: () => import('./weather').then(m => withWidgetViewport(m.Weather))
637
+ */
638
+ declare function withWidgetViewport<P extends {
639
+ size: WidgetSize;
640
+ }>(Component: ComponentType<P>): ComponentType<P>;
641
+
642
+ type ClassValue = ClassValue[] | Record<string, unknown> | string | number | bigint | boolean | null | undefined;
643
+ /**
644
+ * Joins class names, skipping empty ones (the `clsx` input shapes).
645
+ *
646
+ * It does not merge utilities: the package's own classes live in the
647
+ * stylesheet's `components` layer, so a consumer's Tailwind utility already
648
+ * wins over them through the cascade.
649
+ */
650
+ declare function cn(...inputs: ClassValue[]): string;
651
+
652
+ type WidgetLinkProps = {
653
+ href: string;
654
+ children?: ReactNode;
655
+ } & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children' | 'href'>;
656
+ /**
657
+ * Supplies the component that in-app destinations render as, and the origins
658
+ * this app answers for.
659
+ *
660
+ * Widgets link to app routes, but the package cannot import a router: it is
661
+ * mounted in two apps with different navigation, and on atom63.io an in-app
662
+ * portfolio href does not even change route — it opens the detail overlay on
663
+ * the current page. So the host names the component and the widget asks for it.
664
+ *
665
+ * This is context rather than a prop because there is no prop channel to use.
666
+ * Widgets reach the screen through a lazy registry whose entries are
667
+ * `ComponentType<{ size }>`, composed by the agent's slot renderer — threading
668
+ * a slot to them would mean changing that contract in both apps and in the
669
+ * agent package. Navigation is an app-wide singleton, which is what context is
670
+ * for.
671
+ *
672
+ * ## Why `origins` is not just `window.location.origin`
673
+ *
674
+ * Portfolio cards author one absolute `https://atom63.io/...` href for every
675
+ * host, so "is this mine?" is decided by comparing origins. The running origin
676
+ * alone answers that correctly in production and WRONGLY everywhere a change
677
+ * is actually tested: on `localhost:5173` and on a `*.vercel.app` preview,
678
+ * atom63.io's own cards compare as cross-origin and render as external links
679
+ * that leave for production. A host that knows it IS atom63.io says so here,
680
+ * and dev, preview and production agree.
681
+ *
682
+ * Only a host that can route should declare them: the origins decide which
683
+ * links are treated as in-app, so claiming one you cannot route turns a
684
+ * working external link into a dead in-app one.
685
+ *
686
+ * Opt-in by design: with no provider, in-app destinations fall back to a
687
+ * native anchor and full-page navigate. That is a working link, just not a
688
+ * routed one, so a host that forgets this degrades rather than breaks.
689
+ *
690
+ * External destinations never use it — they always open a plain new-tab anchor.
691
+ *
692
+ * @example
693
+ * <WidgetLinkProvider Link={DetailHrefLink} origins={[PORTFOLIO_ORIGIN]}>
694
+ * <AgentChat />
695
+ * </WidgetLinkProvider>
696
+ */
697
+ declare function WidgetLinkProvider({ children, Link, origins, }: {
698
+ children: ReactNode;
699
+ Link: ComponentType<WidgetLinkProps>;
700
+ /** Origins this app serves, besides the one it is running on. */
701
+ origins?: readonly string[];
702
+ }): React.JSX.Element;
703
+ /** The host's in-app link component, or undefined when none was provided. */
704
+ declare function useWidgetLink(): ComponentType<WidgetLinkProps> | undefined;
705
+ /**
706
+ * Resolve a destination against the running origin AND any the host declared.
707
+ *
708
+ * Prefer this over calling `resolveDestination` directly from a view: the bare
709
+ * function cannot see the host's origins, so it reports atom63.io's own cards
710
+ * as external on localhost and on preview deployments.
711
+ */
712
+ declare function useWidgetDestination(href: string | undefined): WidgetDestination | null;
713
+
714
+ export { type ClassValue, WIDGET_BODY_GAP, WIDGET_BODY_INSET, WIDGET_CANONICAL_CELL_PX, WIDGET_DENSITY_SCALE, WIDGET_MAX_PRESENTATION_SCALE, WIDGET_TYPE_FLOOR, WIDGET_TYPE_RAMP, WIDGET_TYPE_ROLE_FLOOR, WIDGET_UNIT_BASE_PX, WIDGET_UNIT_SPAN, type WidgetDensity, type WidgetDestination, WidgetGrid, type WidgetGridProps, WidgetImage, type WidgetInsetMode, type WidgetInsetStyleOptions, type WidgetLinkProps, WidgetLinkProvider, type WidgetPresentationStyle, WidgetSize, WidgetSizeProvider, type WidgetSizeProviderProps, type WidgetSizeStyle, type WidgetSizeStyleOptions, type WidgetTypeFloorRole, type WidgetTypeRampRole, type WidgetTypeRole, type WidgetTypeStyleOptions, type WidgetUnitSpan, type WidgetUnitStyle, WidgetViewport, type WidgetViewportProps, cn, resolveDestination, resolveDestinationKind, useWidgetDestination, useWidgetLink, useWidgetSize, widgetChromeIconStyle, widgetClampRelief, widgetInsetPx, widgetInsetStyle, widgetPresentationStyle, widgetSizeStyle, widgetTypeDesignPx, widgetTypeStyle, widgetUnitStyle, withWidgetViewport, wu, wuClamp, wuMerge, wuStyle };