@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.
- package/LICENSE +27 -0
- package/README.md +29 -0
- package/dist/chunk-F5NV6XJ5.js +418 -0
- package/dist/chunk-F5NV6XJ5.js.map +1 -0
- package/dist/chunk-US2CE3BV.js +222 -0
- package/dist/chunk-US2CE3BV.js.map +1 -0
- package/dist/index.d.ts +714 -0
- package/dist/index.js +206 -0
- package/dist/index.js.map +1 -0
- package/dist/primitives/index.d.ts +123 -0
- package/dist/primitives/index.js +4 -0
- package/dist/primitives/index.js.map +1 -0
- package/dist/runtime/index.d.ts +129 -0
- package/dist/runtime/index.js +236 -0
- package/dist/runtime/index.js.map +1 -0
- package/dist/state/index.d.ts +90 -0
- package/dist/state/index.js +158 -0
- package/dist/state/index.js.map +1 -0
- package/dist/types-C0zDKyo1.d.ts +3 -0
- package/dist/widget-card-BckLTmBY.d.ts +112 -0
- package/package.json +98 -0
- package/src/layout/widget-layout.css +76 -0
- package/src/primitives/widget-avatar.css +153 -0
- package/src/primitives/widget-card.css +128 -0
- package/src/primitives/widget-surface.css +75 -0
- package/src/runtime/widget-runtime.css +136 -0
- package/src/state/widget-state-feedback.css +149 -0
- package/src/styles.css +20 -0
package/dist/index.d.ts
ADDED
|
@@ -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 };
|