@ultralabs/glass 0.0.0-stage → 0.1.1

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 (137) hide show
  1. package/CHANGELOG.md +326 -0
  2. package/DESIGN.md +682 -0
  3. package/LICENSE +21 -0
  4. package/README.md +690 -2
  5. package/dist/esm/index.js +20991 -0
  6. package/dist/types/src/charts/ULCartesianChart.d.ts +177 -0
  7. package/dist/types/src/charts/ULDonutChart.d.ts +65 -0
  8. package/dist/types/src/charts/ULFunnelChart.d.ts +64 -0
  9. package/dist/types/src/charts/ULHeatmapChart.d.ts +40 -0
  10. package/dist/types/src/charts/ULRadarChart.d.ts +19 -0
  11. package/dist/types/src/charts/ULRadialChart.d.ts +48 -0
  12. package/dist/types/src/charts/ULScatterChart.d.ts +49 -0
  13. package/dist/types/src/charts/core.d.ts +287 -0
  14. package/dist/types/src/charts/decimate.d.ts +8 -0
  15. package/dist/types/src/charts/nav.d.ts +368 -0
  16. package/dist/types/src/charts/quadtree.d.ts +9 -0
  17. package/dist/types/src/charts/scales.d.ts +59 -0
  18. package/dist/types/src/charts/timeseries.d.ts +56 -0
  19. package/dist/types/src/components/ULAnchoredSurface/ULAnchoredSurface.d.ts +72 -0
  20. package/dist/types/src/components/ULBatch2/carousel.d.ts +31 -0
  21. package/dist/types/src/components/ULBatch2/hovercard.d.ts +40 -0
  22. package/dist/types/src/components/ULBatch2/layout.d.ts +16 -0
  23. package/dist/types/src/components/ULBatch2/menubar.d.ts +29 -0
  24. package/dist/types/src/components/ULBatch2/navmenu.d.ts +51 -0
  25. package/dist/types/src/components/ULBatch2/resizable.d.ts +48 -0
  26. package/dist/types/src/components/ULBatch2/typography.d.ts +55 -0
  27. package/dist/types/src/components/ULButton/ULButton.d.ts +87 -0
  28. package/dist/types/src/components/ULContainers/ULCard.d.ts +54 -0
  29. package/dist/types/src/components/ULContainers/ULDialog.d.ts +57 -0
  30. package/dist/types/src/components/ULContainers/ULLayout.d.ts +81 -0
  31. package/dist/types/src/components/ULContainers/ULMenu.d.ts +99 -0
  32. package/dist/types/src/components/ULContainers/ULOverlays.d.ts +113 -0
  33. package/dist/types/src/components/ULContainers/contextTarget.d.ts +91 -0
  34. package/dist/types/src/components/ULData/ULData.d.ts +225 -0
  35. package/dist/types/src/components/ULData/ULKpi.d.ts +159 -0
  36. package/dist/types/src/components/ULField/ULField.d.ts +93 -0
  37. package/dist/types/src/components/ULForms/fieldContext.d.ts +39 -0
  38. package/dist/types/src/components/ULForms/forms.d.ts +143 -0
  39. package/dist/types/src/components/ULIsland/ULIsland.d.ts +39 -0
  40. package/dist/types/src/components/ULIsland/headerConfig.d.ts +43 -0
  41. package/dist/types/src/components/ULIsland/navIndicator.d.ts +26 -0
  42. package/dist/types/src/components/ULListbox/ULListbox.d.ts +75 -0
  43. package/dist/types/src/components/ULPickers/ULPickers.d.ts +141 -0
  44. package/dist/types/src/components/ULSegmented/ULSegmented.d.ts +50 -0
  45. package/dist/types/src/components/ULSelection/ULSelection.d.ts +71 -0
  46. package/dist/types/src/components/ULSlider/ULSlider.d.ts +43 -0
  47. package/dist/types/src/components/ULSpinner/ULSpinner.d.ts +8 -0
  48. package/dist/types/src/components/ULStructure/kbd.d.ts +22 -0
  49. package/dist/types/src/components/ULStructure/structure.d.ts +154 -0
  50. package/dist/types/src/components/ULTabs/ULTabs.d.ts +28 -0
  51. package/dist/types/src/components/ULTooltip/anchoredTooltip.d.ts +22 -0
  52. package/dist/types/src/components/actions/actions.d.ts +175 -0
  53. package/dist/types/src/components/actions/core.d.ts +346 -0
  54. package/dist/types/src/components/dashboard/blocks.d.ts +583 -0
  55. package/dist/types/src/components/dashboard/blocks2.d.ts +297 -0
  56. package/dist/types/src/components/dashboard/columnsDrag.d.ts +27 -0
  57. package/dist/types/src/components/shared/ULCheckMark.d.ts +9 -0
  58. package/dist/types/src/components/shared/dev.d.ts +13 -0
  59. package/dist/types/src/components/shared/icons.d.ts +23 -0
  60. package/dist/types/src/glass/ULGlass.d.ts +78 -0
  61. package/dist/types/src/glass/ULGlassGroup.d.ts +16 -0
  62. package/dist/types/src/glass/accent.d.ts +31 -0
  63. package/dist/types/src/glass/contrast.d.ts +78 -0
  64. package/dist/types/src/glass/engine.d.ts +177 -0
  65. package/dist/types/src/glass/glassDebug.d.ts +27 -0
  66. package/dist/types/src/glass/material.d.ts +49 -0
  67. package/dist/types/src/glass/radius.d.ts +2 -0
  68. package/dist/types/src/hooks/useAnchoredMorph.d.ts +20 -0
  69. package/dist/types/src/hooks/usePointerLight.d.ts +6 -0
  70. package/dist/types/src/hooks/useReducedMotion.d.ts +3 -0
  71. package/dist/types/src/index.d.ts +150 -0
  72. package/dist/types/src/island/sectionAccent.d.ts +18 -0
  73. package/dist/types/src/live/ULLiveStatus.d.ts +18 -0
  74. package/dist/types/src/live/liveQueue.d.ts +13 -0
  75. package/dist/types/src/live/liveSource.d.ts +149 -0
  76. package/dist/types/src/live/liveStore.d.ts +72 -0
  77. package/dist/types/src/motion/anchoredMorph.d.ts +175 -0
  78. package/dist/types/src/motion/goo.d.ts +3 -0
  79. package/dist/types/src/motion/lensBubble.d.ts +143 -0
  80. package/dist/types/src/motion/lensSelect.d.ts +31 -0
  81. package/dist/types/src/motion/overlayStack.d.ts +13 -0
  82. package/dist/types/src/motion/placement.d.ts +18 -0
  83. package/dist/types/src/motion/spring.d.ts +20 -0
  84. package/dist/types/src/motion/topLayer.d.ts +13 -0
  85. package/dist/types/src/motion/viewSwap.d.ts +33 -0
  86. package/dist/types/src/motion/virtualAnchor.d.ts +28 -0
  87. package/dist/ul-glass.css +10519 -0
  88. package/dist/ul-glass.js +21034 -0
  89. package/dist/ul-glass.min.js +14 -0
  90. package/dist/ul-glass.min.js.map +7 -0
  91. package/icons/arrow-up-down.svg +5 -0
  92. package/icons/bell.svg +3 -0
  93. package/icons/bold.svg +2 -0
  94. package/icons/calendar.svg +5 -0
  95. package/icons/check.svg +2 -0
  96. package/icons/chevron-down.svg +2 -0
  97. package/icons/chevron-left.svg +2 -0
  98. package/icons/chevron-right.svg +2 -0
  99. package/icons/chevrons-right.svg +3 -0
  100. package/icons/circle-check.svg +3 -0
  101. package/icons/circle-x.svg +4 -0
  102. package/icons/circle.svg +2 -0
  103. package/icons/copy.svg +3 -0
  104. package/icons/ellipsis.svg +4 -0
  105. package/icons/eye.svg +3 -0
  106. package/icons/filter.svg +2 -0
  107. package/icons/flags/LICENSE.md +2 -0
  108. package/icons/flags/cs.svg +1 -0
  109. package/icons/flags/de.svg +1 -0
  110. package/icons/flags/en.svg +1 -0
  111. package/icons/flags/sk.svg +1 -0
  112. package/icons/folder-kanban.svg +5 -0
  113. package/icons/icons.json +1 -0
  114. package/icons/inbox.svg +3 -0
  115. package/icons/info.svg +4 -0
  116. package/icons/layout-dashboard.svg +5 -0
  117. package/icons/layout-grid.svg +5 -0
  118. package/icons/loader-circle.svg +2 -0
  119. package/icons/lock.svg +3 -0
  120. package/icons/mail.svg +3 -0
  121. package/icons/menu.svg +4 -0
  122. package/icons/minus.svg +2 -0
  123. package/icons/panel-left-close.svg +4 -0
  124. package/icons/plus.svg +3 -0
  125. package/icons/refresh-cw.svg +5 -0
  126. package/icons/search.svg +3 -0
  127. package/icons/shield-check.svg +3 -0
  128. package/icons/shopping-bag.svg +4 -0
  129. package/icons/sparkles.svg +6 -0
  130. package/icons/trash-2.svg +6 -0
  131. package/icons/triangle-alert.svg +4 -0
  132. package/icons/upload.svg +4 -0
  133. package/icons/users.svg +5 -0
  134. package/icons/x.svg +3 -0
  135. package/package.json +65 -4
  136. package/tokens/tokens.css +799 -0
  137. package/tokens/tokens.json +1017 -0
@@ -0,0 +1,149 @@
1
+ export type LiveStatus = 'connecting' | 'live' | 'reconnecting' | 'stale' | 'offline' | 'paused' | 'error';
2
+ export interface TransportHandlers {
3
+ open(): void;
4
+ message(data: unknown): void;
5
+ close(info?: {
6
+ code?: number;
7
+ reason?: string;
8
+ fatal?: boolean;
9
+ }): void;
10
+ error(e: unknown): void;
11
+ }
12
+ export interface TransportContext {
13
+ auth: unknown;
14
+ resumeToken: string | null;
15
+ attempt: number;
16
+ }
17
+ export interface TransportConn {
18
+ send?(data: unknown): void;
19
+ close(): void;
20
+ }
21
+ export interface Transport {
22
+ kind: string;
23
+ connect(h: TransportHandlers, ctx: TransportContext): TransportConn;
24
+ }
25
+ export interface RateLimit {
26
+ max: number; /** drop: discard over the limit; coalesce: keep the latest per key and deliver it in the next slot. */
27
+ policy?: 'drop' | 'coalesce';
28
+ key?: (m: unknown) => string;
29
+ }
30
+ export interface LiveSourceOptions<M = unknown> {
31
+ transport: Transport;
32
+ /** Raw frame → message(s). Default: JSON.parse for strings, identity otherwise. Throw / return undefined to reject. */
33
+ parse?: (raw: unknown) => M | M[] | undefined;
34
+ /** Optional validation: a predicate, or a zod-like { safeParse }. Rejected messages are counted and dropped. */
35
+ schema?: ((m: unknown) => boolean) | {
36
+ safeParse(m: unknown): {
37
+ success: boolean;
38
+ };
39
+ };
40
+ reconnect?: {
41
+ base?: number;
42
+ max?: number;
43
+ retries?: number;
44
+ } | false;
45
+ heartbeat?: {
46
+ interval?: number;
47
+ timeout?: number;
48
+ ping?: () => unknown;
49
+ isPong?: (m: M) => boolean;
50
+ } | false;
51
+ /** frame (default): one delivery per animation frame; or a fixed interval in ms. */
52
+ batch?: 'frame' | number;
53
+ maxMessageBytes?: number;
54
+ rateLimit?: RateLimit;
55
+ /** Dedupe by id (LRU window) and drop out-of-order messages by per-key sequence. */
56
+ idOf?: (m: M) => string | undefined;
57
+ seqOf?: (m: M) => {
58
+ key: string;
59
+ seq: number;
60
+ } | undefined;
61
+ /** Auth supplied by the app (never put it in the URL). Called before every (re)connect; its result goes to the transport. */
62
+ getAuth?: () => unknown | Promise<unknown>;
63
+ /** Resume after reconnect: the app keeps the token (e.g. last event id) and decides what it means. */
64
+ resume?: {
65
+ get(): string | null;
66
+ onMessage?(m: M): void;
67
+ };
68
+ /** Buffer while paused / hidden; oldest dropped beyond the cap. */
69
+ bufferCap?: number;
70
+ pauseWhenHidden?: boolean;
71
+ staleAfter?: number;
72
+ }
73
+ export interface LiveStats {
74
+ received: number;
75
+ delivered: number;
76
+ dropped: number;
77
+ coalesced: number;
78
+ duplicates: number;
79
+ outOfOrder: number;
80
+ rejected: number;
81
+ oversized: number;
82
+ reconnects: number;
83
+ buffered: number;
84
+ bufferMax: number;
85
+ }
86
+ export interface LiveSource<M = unknown> {
87
+ subscribe(fn: (batch: M[]) => void): () => void;
88
+ onStatus(fn: (s: LiveStatus, info?: {
89
+ attempt?: number;
90
+ retryIn?: number;
91
+ error?: unknown;
92
+ }) => void): () => void;
93
+ readonly status: LiveStatus;
94
+ readonly stats: LiveStats;
95
+ start(): void;
96
+ stop(): void;
97
+ pause(): void;
98
+ resume(): void;
99
+ readonly paused: boolean;
100
+ send(data: unknown): void;
101
+ /** Drop the connection and reconnect now (resets backoff). */
102
+ reconnectNow(): void;
103
+ }
104
+ /** Refuses credentials in the URL and insecure schemes outside localhost. */
105
+ export declare function checkLiveUrl(url: string, secure: 'ws' | 'http', allowInsecure?: boolean): URL;
106
+ export interface WebSocketTransportOptions {
107
+ /** How the app's auth reaches the server: as a subprotocol value, or as the first message after open. Default first-message. */
108
+ authStrategy?: 'first-message' | 'protocol' | 'none';
109
+ allowInsecure?: boolean;
110
+ }
111
+ export declare function websocket(url: string, protocols?: string | string[], o?: WebSocketTransportOptions): Transport;
112
+ /** Server-sent events. Auth only through cookies (withCredentials): EventSource cannot set headers, and URLs never carry tokens. */
113
+ export declare function sse(url: string, o?: {
114
+ withCredentials?: boolean;
115
+ events?: string[];
116
+ allowInsecure?: boolean;
117
+ }): Transport;
118
+ /** Polling: fn returns the new messages since the last call (the app decides how). */
119
+ export declare function polling(fn: (ctx: TransportContext) => Promise<unknown[]>, interval?: number): Transport;
120
+ export interface MockOptions {
121
+ /** Messages per second. */
122
+ rate?: number;
123
+ /** ms of latency (+ random jitter). */
124
+ latency?: number;
125
+ jitter?: number;
126
+ /** 0..1 probabilities. */
127
+ drops?: number;
128
+ duplicates?: number;
129
+ reorder?: number;
130
+ /** Generates message number `seq`. */
131
+ generate: (seq: number) => unknown;
132
+ /** Stop answering (simulated dead connection, no close event): heartbeat test. */
133
+ silent?: boolean;
134
+ /** Fail the first n connects (backoff test). */
135
+ failConnects?: number;
136
+ }
137
+ export interface MockControls {
138
+ set(o: Partial<MockOptions>): void;
139
+ burst(n: number): void;
140
+ disconnect(code?: number): void;
141
+ readonly options: MockOptions;
142
+ readonly connects: number;
143
+ readonly sent: number;
144
+ inject(raw: unknown): void;
145
+ }
146
+ export declare function mock(opts: MockOptions): Transport & {
147
+ controls: MockControls;
148
+ };
149
+ export declare function createLiveSource<M = unknown>(o: LiveSourceOptions<M>): LiveSource<M>;
@@ -0,0 +1,72 @@
1
+ import type { LiveSource } from './liveSource.js';
2
+ export type LiveOp<R> = {
3
+ op: 'upsert';
4
+ value: R;
5
+ } | {
6
+ op: 'patch';
7
+ key: string;
8
+ value: Partial<R>;
9
+ } | {
10
+ op: 'remove';
11
+ key: string;
12
+ } | {
13
+ op: 'reset';
14
+ values: R[];
15
+ };
16
+ export interface LiveCommit {
17
+ inserted: string[];
18
+ updated: string[];
19
+ removed: string[];
20
+ reset: boolean;
21
+ version: number;
22
+ }
23
+ export interface LiveStore<R> {
24
+ get(key: string): R | undefined;
25
+ keys(): string[];
26
+ values(): R[];
27
+ readonly size: number;
28
+ readonly version: number;
29
+ upsert(value: R): void;
30
+ patch(key: string, value: Partial<R>): void;
31
+ remove(key: string): void;
32
+ reset(values: R[]): void;
33
+ apply(op: LiveOp<R> | LiveOp<R>[]): void;
34
+ /** Every commit (structure + values). */
35
+ subscribe(fn: (c: LiveCommit) => void): () => void;
36
+ /** One key's value changed (or it was removed). */
37
+ subscribeKey(key: string, fn: () => void): () => void;
38
+ /** Stop committing (ops are still applied to the data; listeners are told once on resume). */
39
+ pause(): void;
40
+ resume(): void;
41
+ readonly paused: boolean;
42
+ /** Synchronous commit (tests). */
43
+ flush(): void;
44
+ }
45
+ export interface LiveStoreOptions<R> {
46
+ key: (r: R) => string;
47
+ /** patch merge (default shallow). */
48
+ merge?: (prev: R, next: Partial<R>) => R;
49
+ /** Commits per second cap. Default --ul-live-max-fps. */
50
+ maxRate?: number;
51
+ }
52
+ export declare function createLiveStore<R>(o: LiveStoreOptions<R>): LiveStore<R>;
53
+ /** Keyed store fed by a live source. The store is stable for the component's life; the source is started / stopped with it. */
54
+ export declare function useLiveStore<R, M = unknown>(source: LiveSource<M> | null, o: LiveStoreOptions<R> & {
55
+ toOps?: (m: M) => LiveOp<R> | LiveOp<R>[];
56
+ initial?: R[];
57
+ autoStart?: boolean;
58
+ }): LiveStore<R>;
59
+ /** Re-renders on structure changes only (insert / remove / reset). */
60
+ export declare function useLiveKeys<R>(store: LiveStore<R>): string[];
61
+ /** One row; re-renders only when that key changes. */
62
+ export declare function useLiveRow<R>(store: LiveStore<R>, key: string): R | undefined;
63
+ /** Any derived value; re-renders only when `eq` says it changed. */
64
+ export declare function useLiveSelector<R, T>(store: LiveStore<R>, select: (s: LiveStore<R>) => T, eq?: (a: T, b: T) => boolean): T;
65
+ /** Live status of a source (re-renders on status changes). */
66
+ export declare function useLiveStatus(source: LiveSource | null): {
67
+ status: string;
68
+ info?: {
69
+ attempt?: number;
70
+ retryIn?: number;
71
+ };
72
+ };
@@ -0,0 +1,175 @@
1
+ import { type Align, type Side } from './placement.js';
2
+ export interface MorphTokens {
3
+ enter: number;
4
+ exit: number;
5
+ overshoot: number;
6
+ stretch: number;
7
+ goo: boolean;
8
+ stagger: number;
9
+ offset: number;
10
+ gooOpacity: number;
11
+ lag: number;
12
+ }
13
+ export interface MorphParts {
14
+ anchor: HTMLElement;
15
+ surface: HTMLElement;
16
+ stage?: HTMLElement | null;
17
+ goo?: HTMLElement | null;
18
+ /** Optional soft scrim (modals, drawers): its opacity follows the same timeline (never glass). */
19
+ scrim?: HTMLElement | null;
20
+ }
21
+ export interface MorphOptions {
22
+ side?: Side;
23
+ align?: Align;
24
+ offset?: number;
25
+ /** The surface is already laid out at its final rect by its owner (no placement); side is derived from geometry. Works inside scaled ancestors. */
26
+ manual?: boolean;
27
+ /**
28
+ * Where the surface settles. anchored (default): beside the anchor (computePlacement). center: viewport centre (modal,
29
+ * command palette). top | bottom | left | right: pinned to that viewport edge (sheets, drawers, mobile bottom sheet).
30
+ * The morph always starts on the anchor (trigger, edge sentinel or pointer point), so the motion is the same.
31
+ */
32
+ layout?: 'anchored' | 'center' | 'top' | 'bottom' | 'left' | 'right';
33
+ /** Keep the anchor visible + clickable through an even-odd hole while morphing (default true). false: the surface is above the anchor from frame one (overlay opened from a button inside another dialog surface). */
34
+ anchorOnTop?: boolean;
35
+ /** Covered (modal) surface: owner put it in the top layer; never a hole; the first map is generated after the first frame. */
36
+ coverAnchor?: boolean;
37
+ /** Placement overlaps the anchor with this inset (px) so the surface covers it in every frame (non-modal covered popovers). */
38
+ overlap?: number;
39
+ /**
40
+ * Page scroll while open. lock: page scroll locked (menus; scrolling inside the surface still works). follow: the surface
41
+ * tracks the anchor's current rect every frame (same frame, transform only, flip re-evaluated). fixed: stays where it
42
+ * opened. close: any scroll outside the surface requests close. Default follow.
43
+ */
44
+ scrollBehavior?: 'lock' | 'follow' | 'fixed' | 'close';
45
+ /** Anchor fully out of view: keep (default) | hide (visually hidden, fades back) | close. */
46
+ onAnchorHidden?: 'keep' | 'hide' | 'close';
47
+ /** Called for scrollBehavior "close" and onAnchorHidden "close". */
48
+ onRequestClose?: () => void;
49
+ }
50
+ export declare function lockPageScroll(owner: HTMLElement): void;
51
+ export declare function unlockPageScroll(owner: HTMLElement): void;
52
+ export declare const isPageScrollLocked: () => boolean;
53
+ declare const morphConfig: {
54
+ timeScale: number;
55
+ reducedMotion: 'auto' | 'reduce' | 'no-preference';
56
+ };
57
+ /** Global knobs. `timeScale` 4 = slow motion ×0.25. `reducedMotion` overrides the media query (tests). */
58
+ export declare function configureMorph(next: Partial<typeof morphConfig>): void;
59
+ export declare const getMorphTimeScale: () => number;
60
+ export declare const isMorphReduced: () => boolean;
61
+ /** CSS linear() of the shared overshoot spring (--ul-pop-overshoot); for container motion that must match the morph (sidebar width). */
62
+ export declare const overshootEase: (os?: number) => string;
63
+ export declare function readMorphTokens(): MorphTokens;
64
+ export declare class AnchoredMorph {
65
+ anchor: HTMLElement;
66
+ surface: HTMLElement;
67
+ stage: HTMLElement | null;
68
+ goo: HTMLElement | null;
69
+ scrim: HTMLElement | null;
70
+ opts: MorphOptions;
71
+ side: Side;
72
+ private tau;
73
+ private anim;
74
+ private stageAnim;
75
+ /** Backdrop shell (UL-635): the only blurred element while the morph runs; see ensureShell(). */
76
+ private shell;
77
+ private shellAnim;
78
+ private shellRaf;
79
+ private shellTimer;
80
+ private shellFade;
81
+ private shellFilter;
82
+ private seg;
83
+ private loop;
84
+ private fin;
85
+ private geo;
86
+ private tl;
87
+ private tok;
88
+ private hole;
89
+ private phase;
90
+ private k;
91
+ private prevOverflow;
92
+ private prevPadding;
93
+ private follow;
94
+ private followOn;
95
+ private fa;
96
+ private vp;
97
+ private dxy;
98
+ private lastIn;
99
+ private lastInAnim;
100
+ private hiddenByAnchor;
101
+ private closeAsked;
102
+ private wroteTranslate;
103
+ /** Set by an owner before closing (swipe-dismissed toast): the next exit fades in place instead of returning to the anchor. */
104
+ nextExitFade: boolean;
105
+ /** Instrumentation: last follow frame. */
106
+ followFrame: {
107
+ dx: number;
108
+ dy: number;
109
+ side: string;
110
+ hidden: boolean;
111
+ };
112
+ constructor(parts: MorphParts, opts?: MorphOptions);
113
+ setOptions(opts: MorphOptions): void;
114
+ get animating(): boolean;
115
+ private onViewport;
116
+ private mode;
117
+ private startOpenBehavior;
118
+ /** Stop and fold the follow offset into left / top, so exit keyframes start from where the surface is. */
119
+ private stopOpenBehavior;
120
+ private onCloseScroll;
121
+ private askClose;
122
+ private followTick;
123
+ /** Measure at final size, run collision-aware placement, pin the surface (position: fixed). */
124
+ /** Anchor rect in the surface's local px (divides out ancestor scale in manual mode). */
125
+ private anchorRect;
126
+ /** Final top-left + side for the current layout. Side = which side of the anchor the surface sits on (origin + stretch axis). */
127
+ private placeFor;
128
+ private nestPad;
129
+ /** The parent menu surface when this is a sideways menu opened from a row inside another menu surface. */
130
+ private nestedParent;
131
+ private scrimTo;
132
+ place(): void;
133
+ private buildGeo;
134
+ private timeline;
135
+ private currentTau;
136
+ private holeRect;
137
+ private ensureHole;
138
+ /** Surface clip for one pose: even-odd hole at the anchor (zero-size once they no longer overlap). */
139
+ private clipFor;
140
+ private applyHole;
141
+ private clearHole;
142
+ private emit;
143
+ private ensureShell;
144
+ /** Interrupted / not a shell run: no shell, the surface owns its blur again at once. */
145
+ private dropShell;
146
+ /** Settled: frame 0 the surface is already static (no blur), frame 1 blur back on the surface + shell hidden, frame 2 shell gone. */
147
+ private handoverShell;
148
+ private begin;
149
+ /** Cancel animations and remove every temporary style (hole included). */
150
+ private stop;
151
+ /** Visual rect of the surface right now (animation applied), in the surface's local px. Read BEFORE stop(). */
152
+ private visualPose;
153
+ private run;
154
+ private drawGoo;
155
+ private hideGoo;
156
+ /** Slide out from behind the anchor. Resolves true when settled, false if interrupted. */
157
+ enter(): Promise<boolean>;
158
+ /** Exact time-reverse of enter (faster), back under the anchor's CURRENT rect. Resolves true when absorbed. */
159
+ exit(): Promise<boolean>;
160
+ /** Anchor gone or off-screen: scale + fade at the last known position. */
161
+ private fallbackExit;
162
+ /** Reduced motion: 150ms opacity + small scale from the anchor side. No stretch, goo or overshoot. */
163
+ private simple;
164
+ /** Owner resized / moved the SETTLED surface (dialog view swap): the next exit starts from this rect. */
165
+ setFinalRect(L: number, T: number, w: number, h: number): void;
166
+ /** Final top-left for a surface of this size under the current layout (dialog view swap). */
167
+ finalFor(w: number, h: number): {
168
+ L: number;
169
+ T: number;
170
+ };
171
+ /** Owner moved the SETTLED surface (sheet / toast drag): fold the offset into the final rect so the exit starts there. */
172
+ shiftFinal(dx: number, dy: number): void;
173
+ destroy(): void;
174
+ }
175
+ export {};
@@ -0,0 +1,3 @@
1
+ export declare const GOO_FILTER_ID = "ul-goo";
2
+ /** Shared gooey filter (blur + alpha threshold). Applied only to non-glass helper layers, never to glass or its ancestors. */
3
+ export declare function ensureGooFilter(): string;
@@ -0,0 +1,143 @@
1
+ export type LensKind = 'switch' | 'slider' | 'tabs';
2
+ export interface LensTokens {
3
+ scale: number;
4
+ overshoot: number;
5
+ grow: number;
6
+ shrink: number;
7
+ dragStretch: number;
8
+ magnify: number;
9
+ rubber: number;
10
+ flick: number;
11
+ lead: number;
12
+ trail: number;
13
+ overgrow: number;
14
+ radiusMode: 'concentric' | 'fixed';
15
+ radius: number;
16
+ settleHold: number;
17
+ follow: number;
18
+ toggle: number;
19
+ pressGlide: number;
20
+ zetaMin: number;
21
+ settle: number;
22
+ shrinkStart: number;
23
+ linger: number;
24
+ }
25
+ export interface LensGeometry {
26
+ c: number;
27
+ cc: number;
28
+ w: number;
29
+ h: number;
30
+ r: number;
31
+ wrap: {
32
+ lo: number;
33
+ hi: number;
34
+ cross: number;
35
+ r: number;
36
+ };
37
+ }
38
+ export interface LensOptions {
39
+ kind: LensKind;
40
+ axis?: 'x' | 'y';
41
+ /** Control root: the bubble is positioned relative to its (cached) viewport rect; tokens, theme and accent are read from it. */
42
+ host: HTMLElement;
43
+ geometry: () => LensGeometry;
44
+ /** Resting thumb / indicator elements: hidden while the bubble is visible. */
45
+ knobs?: () => (HTMLElement | null)[];
46
+ /** Persistent + follow: rest size at a position between items (tabs of different widths). */
47
+ geometryAt?: (c: number) => Partial<LensGeometry>;
48
+ /** True while the owner's own target is still moving (slider follow spring, switch travel). */
49
+ busy?: () => boolean;
50
+ /** Bubble shown / hidden (owner can e.g. disable its own transitions). */
51
+ onLive?: (live: boolean) => void;
52
+ /** 'root' (default): pooled element in the root layer, hidden at rest. 'host': ONE persistent element inside the host that
53
+ * IS the resting indicator (flat capsule at rest, bubble when active): tabs, segmented. */
54
+ mount?: 'root' | 'host';
55
+ /** The bubble follows its target through a critically damped spring (--ul-lens-follow) instead of directly (tabs). */
56
+ follow?: boolean;
57
+ /** Release behaviour (switch, tabs, segmented): the thumb SETTLES on an elastic spring (--ul-lens-settle-duration) and the
58
+ * bubble starts shrinking at --ul-lens-shrink-start of it; gone ≤ --ul-lens-release-linger after release. The thumb may
59
+ * finish the settle alone (onFrame keeps reporting the position). Default false (slider: shrink after settle). */
60
+ earlyShrink?: boolean;
61
+ /** Called every frame with the bubble's settled-spring position (host px), null when the motion has ended. */
62
+ onFrame?: (c: number | null) => void;
63
+ }
64
+ export declare const zetaFor: (r: number) => number;
65
+ export declare function readLensTokens(el: Element, kind: LensKind): LensTokens;
66
+ /** Rubber band beyond [lo, hi]: excess d → (1 − 1 / (d·c / dim + 1)) · dim (iOS-style). */
67
+ export declare function rubberBand(x: number, lo: number, hi: number, c?: number, dim?: number): number;
68
+ export declare class LensBubble {
69
+ o: LensOptions;
70
+ enabled: boolean;
71
+ private el;
72
+ private tok;
73
+ private host;
74
+ private pressed;
75
+ private holdUntil;
76
+ private quick;
77
+ private g;
78
+ private a;
79
+ private b;
80
+ private fade;
81
+ private lastC;
82
+ private tv;
83
+ private stillMs;
84
+ private raf;
85
+ private last;
86
+ private frozen;
87
+ private age;
88
+ private live;
89
+ private f;
90
+ private glideT;
91
+ private pace;
92
+ private holdMs;
93
+ private persistent;
94
+ private settleT;
95
+ private releaseAt;
96
+ private relK;
97
+ private coast;
98
+ /** Last frame, for tests / instrumentation. */
99
+ frame: {
100
+ x: number;
101
+ y: number;
102
+ w: number;
103
+ h: number;
104
+ r: number;
105
+ k: number;
106
+ g: number;
107
+ alpha: number;
108
+ c: number;
109
+ t: number;
110
+ live: boolean;
111
+ mode: string;
112
+ el: HTMLElement | null;
113
+ };
114
+ constructor(o: LensOptions);
115
+ get active(): boolean;
116
+ press(): void;
117
+ /** Travel the bubble to the owner's new target on a slow glide (ms on the motion clock). */
118
+ glide(ms: number): void;
119
+ /**
120
+ * Click / keyboard / programmatic toggle: grow + travel + settle + shrink in about --ul-switch-toggle-duration
121
+ * (keyboard and programmatic 70 %). Travel 30 % (overlapping the grow), settle hold 11 %, shrink 34 % (measured total ≈ token).
122
+ */
123
+ toggle(kind?: 'click' | 'key'): void;
124
+ /** Persistent indicator: place the resting form on the owner's current target (layout change, no press). */
125
+ private warned;
126
+ rest(): void;
127
+ release(): void;
128
+ /** Owner's target moved without a press (keyboard, click-to-jump, programmatic): keep the bubble up while it travels. */
129
+ nudge(quick?: number): void;
130
+ /** Cancel immediately (unmount, disable). */
131
+ kill(): void;
132
+ destroy(): void;
133
+ private start;
134
+ /** Cache the host rect (no layout reads per frame); refreshed on scroll / resize while live. */
135
+ private measureHost;
136
+ private show;
137
+ /** Same node as the resting indicator: inflate from where it rests now (a/b already there). */
138
+ private showPersistent;
139
+ private hide;
140
+ private activeSize;
141
+ private tick;
142
+ private write;
143
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Press-and-hold / drag selection with the shared lens bubble, for lists with one selected item and a resting indicator
3
+ * (ULSegmentedControl, ULTabs). Framework-free; one implementation for both.
4
+ *
5
+ * Press anywhere in the list: the bubble appears on the indicator (pressed the selected item) or glides to the pressed
6
+ * item. While held it follows the pointer along the axis (rubber band past the first / last item, elastic two-edge
7
+ * model); the item under the bubble centre gets [data-ul-preview]. Release: the bubble settles on the nearest item to
8
+ * its centre (+ flick projection) and THAT item is selected (onSelect, only on release). A press without movement
9
+ * selects the pressed item through the same path. Esc / pointercancel restore. Keyboard / programmatic changes call
10
+ * travel(from, to). Touch: the list keeps touch-action pan-y (horizontal) / pan-x (vertical) so the page still scrolls.
11
+ */
12
+ import { LensBubble } from './lensBubble.js';
13
+ export interface LensSelectOptions {
14
+ list: HTMLElement;
15
+ axis?: 'x' | 'y';
16
+ /** Enabled items in visual order. */
17
+ items: () => HTMLElement[];
18
+ selected: () => HTMLElement | null;
19
+ /** Resting indicator(s) hidden while the bubble is visible. */
20
+ indicator?: () => HTMLElement | null;
21
+ onSelect: (item: HTMLElement) => void;
22
+ enabled?: () => boolean;
23
+ }
24
+ export interface LensSelect {
25
+ bubble: LensBubble;
26
+ travel(from: HTMLElement | null, to: HTMLElement | null, kind?: 'click' | 'key'): void;
27
+ syncRest(): void;
28
+ consumeClick(): boolean;
29
+ destroy(): void;
30
+ }
31
+ export declare function createLensSelect(o: LensSelectOptions): LensSelect;
@@ -0,0 +1,13 @@
1
+ /** Register an open overlay; `parts` (its scrim) count as inside it. A modal marks the layer below as covered. Returns the release. */
2
+ export declare function pushOverlay(el: HTMLElement, parts?: (HTMLElement | null | undefined)[], modal?: boolean): () => void;
3
+ export declare const isTopOverlay: (el: HTMLElement | null) => boolean;
4
+ export declare const overlayDepth: () => number;
5
+ /** Is `t` inside an overlay opened after `el` (a descendant layer, or its scrim)? */
6
+ export declare function inLaterOverlay(el: HTMLElement, t: Node | null): boolean;
7
+ export declare function focusables(root: HTMLElement): HTMLElement[];
8
+ export interface TrapOptions {
9
+ initial?: HTMLElement | string | null;
10
+ returnTo?: HTMLElement | null;
11
+ }
12
+ /** Traps Tab inside `root` while it is the top overlay; focuses the initial element; returns focus on release. */
13
+ export declare function trapFocus(root: HTMLElement, o?: TrapOptions): () => void;
@@ -0,0 +1,18 @@
1
+ export type Side = 'top' | 'bottom' | 'left' | 'right';
2
+ export type Align = 'start' | 'center' | 'end';
3
+ export interface PlacementOptions {
4
+ side?: Side;
5
+ align?: Align;
6
+ offset?: number;
7
+ padding?: number;
8
+ /** Cover the anchor instead of sitting beside it: the surface overlaps the anchor rect with this inset on the leading edge and the aligned edge (covered non-modal popovers). */
9
+ cover?: number;
10
+ }
11
+ export interface Placement {
12
+ x: number;
13
+ y: number;
14
+ side: Side;
15
+ align: Align;
16
+ }
17
+ /** Side/alignment with collision detection: flips to the opposite side if it has more room, then shifts into the viewport. */
18
+ export declare function computePlacement(a: DOMRect, w: number, h: number, { side, align, offset, padding, cover }?: PlacementOptions): Placement;
@@ -0,0 +1,20 @@
1
+ export interface SpringParams {
2
+ stiffness: number;
3
+ damping: number;
4
+ mass?: number;
5
+ }
6
+ export interface Spring {
7
+ (progress: number): number;
8
+ /** Natural settle time of the spring in ms (pair with the matching duration token). */
9
+ settleMs: number;
10
+ /** CSS `linear()` easing string; identical to the generated --ul-ease-* token. */
11
+ toCSS(points?: number): string;
12
+ }
13
+ /** Semi-implicit Euler spring from 0 to 1. Same algorithm as scripts/build-tokens.mjs. */
14
+ export declare function createSpring({ stiffness, damping, mass }: SpringParams): Spring;
15
+ export declare const springs: {
16
+ bouncy: Spring;
17
+ smooth: Spring;
18
+ snappy: Spring;
19
+ };
20
+ export type SpringName = keyof typeof springs;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Shared top-layer helper (popover="manual"; fallback max z-index). Order of calls = paint order.
3
+ * Modal (covered) surfaces lift scrim → goo → surface. Non-modal layers that must stay above every modal
4
+ * (the toast stack) register with keepOnTop(): they are re-promoted after any later lift, so a modal opened
5
+ * AFTER a toast still paints below it. Non-modal layers carry data-ul-nonmodal-layer: never "outside" for a
6
+ * modal's outside-click / focus trap, never focused by us, never dimmed by a scrim (they are above it).
7
+ */
8
+ export declare const hasPopoverApi: boolean;
9
+ export declare function toTopLayer(n: HTMLElement): void;
10
+ /** Register a non-modal layer that stays above every modal. Returns the release. */
11
+ export declare function keepOnTop(n: HTMLElement): () => void;
12
+ /** Test hook: top-layer order of the open popovers we manage (last = topmost). */
13
+ export declare const topLayerOrder: () => HTMLElement[];
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Same-surface view swap (shared by ULDialogSurface push / pop and the phone menu drill-in).
3
+ * X fades out with a directional slide, the surface morphs left / top / width / height to Y's MEASURED size on the dialog
4
+ * spring, Y's blocks enter at --ul-dialog-enter-at with --ul-dialog-stagger. Interruptible: it always starts from the
5
+ * surface's current visual rect and X's current opacity. Reduced motion: 150ms crossfade, geometry instant.
6
+ */
7
+ import { type AnchoredMorph } from './anchoredMorph.js';
8
+ export interface SwapAnims {
9
+ surf?: Animation;
10
+ out: Animation[];
11
+ inn: Animation[];
12
+ raf: number;
13
+ }
14
+ export declare const newSwapAnims: () => SwapAnims;
15
+ export interface SwapOptions {
16
+ surface: HTMLElement;
17
+ from: HTMLElement | null | undefined;
18
+ to: HTMLElement;
19
+ /** 1 = forward (push / drill in), −1 = back. */
20
+ dir: 1 | -1;
21
+ morph: AnchoredMorph | null;
22
+ anims: SwapAnims;
23
+ /** Called after X is out of flow and Y is in flow, before measuring (size class changes). */
24
+ prepare?: () => void;
25
+ /** Final placement; default the morph's finalFor(w, h). */
26
+ place?: (w: number, h: number) => {
27
+ L: number;
28
+ T: number;
29
+ };
30
+ onDone?: () => void;
31
+ }
32
+ export declare function cancelSwap(A: SwapAnims): void;
33
+ export declare function runViewSwap(o: SwapOptions): void;