@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,8 @@
1
+ import * as React from 'react';
2
+ import './ULSpinner.css';
3
+ export interface ULSpinnerProps extends React.HTMLAttributes<HTMLSpanElement> {
4
+ /** Announced to screen readers. Omit when the parent already sets aria-busy (buttons, fields). */
5
+ label?: string;
6
+ }
7
+ /** Busy indicator in currentColor. Reduced motion slows it down instead of stopping it. */
8
+ export declare function ULSpinner({ label, className, ...rest }: ULSpinnerProps): React.JSX.Element;
@@ -0,0 +1,22 @@
1
+ import * as React from 'react';
2
+ import './kbd.css';
3
+ export type Plat = 'mac' | 'other';
4
+ export type KLoc = 'en' | 'sk' | 'de' | 'cs';
5
+ export declare const kloc: (l?: string) => KLoc;
6
+ /** mac-like = macOS / iOS / iPadOS (userAgentData when available, then platform / UA). */
7
+ export declare function detectPlatform(): Plat;
8
+ /** "Mod+Shift+K" → caps + spoken name for the platform. */
9
+ export declare function formatKeys(combo: string, platform?: Plat, locale?: string): {
10
+ cap: string;
11
+ name: string;
12
+ }[];
13
+ export interface ULKbdProps {
14
+ /** "Mod+K" (Mod = ⌘ on Apple, Ctrl elsewhere) or a sequence ["G", "D"] (pressed one after another). Or children for a single literal cap. */
15
+ keys?: string | string[];
16
+ children?: React.ReactNode;
17
+ platform?: 'auto' | Plat;
18
+ size?: 'sm' | 'md';
19
+ locale?: string;
20
+ className?: string;
21
+ }
22
+ export declare function ULKbd({ keys, children, platform, size, locale, className }: ULKbdProps): React.JSX.Element;
@@ -0,0 +1,154 @@
1
+ import * as React from 'react';
2
+ import { type ContextMenuProps } from '../ULContainers/contextTarget.js';
3
+ import '../shared/lens.css';
4
+ import '../ULSegmented/ULSegmented.css';
5
+ import './structure.css';
6
+ import { ULKbd, formatKeys, detectPlatform, type ULKbdProps } from './kbd.js';
7
+ export { ULKbd, formatKeys, detectPlatform };
8
+ export type { ULKbdProps };
9
+ export interface ULSeparatorProps {
10
+ orientation?: 'horizontal' | 'vertical'; /** optional centred label (horizontal only) */
11
+ label?: React.ReactNode; /** decorative = no separator role (default true when it only spaces content) */
12
+ decorative?: boolean;
13
+ className?: string;
14
+ style?: React.CSSProperties;
15
+ }
16
+ export declare function ULSeparator({ orientation, label, decorative, className, style }: ULSeparatorProps): React.JSX.Element;
17
+ export type AlertTone = 'info' | 'success' | 'warning' | 'danger' | 'neutral';
18
+ export interface ULAlertProps {
19
+ tone?: AlertTone;
20
+ title?: React.ReactNode;
21
+ description?: React.ReactNode;
22
+ children?: React.ReactNode;
23
+ icon?: React.ReactNode | false;
24
+ action?: React.ReactNode;
25
+ dismissible?: boolean;
26
+ onDismiss?: () => void;
27
+ dismissLabel?: string;
28
+ locale?: string;
29
+ className?: string;
30
+ style?: React.CSSProperties;
31
+ }
32
+ export declare function ULAlert({ tone, title, description, children, icon, action, dismissible, onDismiss, dismissLabel, locale, className, style }: ULAlertProps): React.JSX.Element | null;
33
+ export interface ULAlertDialogProps {
34
+ /** Controlled open state. */ open: boolean; /** Called with the next open state (trigger, Esc, outside click, close button). */
35
+ onOpenChange?: (o: boolean) => void; /** Trigger element: the surface morphs from it and focus returns to it on close. */
36
+ triggerRef?: React.RefObject<HTMLElement | null>;
37
+ /** Heading (labels the dialog / popover via aria-labelledby). */ title: React.ReactNode; /** Text explaining the consequence (aria-describedby). */
38
+ description?: React.ReactNode; /** Extra content (e.g. ULTypeToConfirm). */
39
+ children?: React.ReactNode;
40
+ /** Confirm button label. */ actionLabel?: string; /** Cancel button label. Default localised "Cancel". */
41
+ cancelLabel?: string; /** "default" | "destructive" (destructive tone on the action button). */
42
+ tone?: 'default' | 'destructive';
43
+ /** async: runs through the action core (loading / success / error); the dialog closes on success */
44
+ onAction: () => Promise<unknown> | unknown;
45
+ /** Called on Cancel / Esc before closing. */ onCancel?: () => void;
46
+ /** type-to-confirm text (reuses ULConfirmAction's field) */
47
+ typeToConfirm?: string;
48
+ /** "en" | "sk" | "de" | "cs" for built-in strings. Default "en". */ locale?: string;
49
+ /** @internal tests */ surfaceRef?: React.MutableRefObject<HTMLElement | null>;
50
+ }
51
+ export declare function ULAlertDialog({ open, onOpenChange, triggerRef, title, description, children, actionLabel, cancelLabel, tone, onAction, onCancel, typeToConfirm, locale, surfaceRef }: ULAlertDialogProps): React.JSX.Element;
52
+ /** Inside an open dialog: confirm through useDialog().push (same surface morphs, no second modal). Resolves true on action success, false on cancel / back. */
53
+ export declare function useAlertDialog(): (o: Omit<ULAlertDialogProps, "open" | "onOpenChange" | "triggerRef"> & {
54
+ triggerRef?: React.RefObject<HTMLElement | null>;
55
+ }) => Promise<boolean>;
56
+ export interface ULConfirmPopoverProps {
57
+ open: boolean; /** Called with the next open state (trigger, Esc, outside click, close button). */
58
+ onOpenChange: (o: boolean) => void; /** Trigger element: the surface morphs from it and focus returns to it on close. */
59
+ triggerRef: React.RefObject<HTMLElement | null>; /** Heading (labels the dialog / popover via aria-labelledby). */
60
+ title: React.ReactNode; /** Text under the title. */
61
+ description?: React.ReactNode; /** Confirm button label. */
62
+ actionLabel?: string; /** Cancel button label. Default localised "Cancel". */
63
+ cancelLabel?: string; /** "default" | "destructive" (destructive tone on the action button). */
64
+ tone?: 'default' | 'destructive'; /** Runs on confirm; a promise shows loading on the action button. */
65
+ onAction: () => Promise<unknown> | unknown; /** Preferred side: "top" | "bottom" | "left" | "right" (flips when there is no room). */
66
+ side?: 'top' | 'bottom' | 'left' | 'right'; /** "en" | "sk" | "de" | "cs" for built-in strings. Default "en". */
67
+ locale?: string;
68
+ }
69
+ /** Quick confirmation on the existing ULPopover (anchored morph, non-modal). Focus starts on Cancel; Esc / outside click cancel. */
70
+ export declare function ULConfirmPopover({ open, onOpenChange, triggerRef, title, description, actionLabel, cancelLabel, tone, onAction, side, locale }: ULConfirmPopoverProps): React.JSX.Element;
71
+ export interface ToggleItem {
72
+ value: string;
73
+ label?: React.ReactNode;
74
+ icon?: React.ReactNode; /** icon-only items: accessible name + tooltip */
75
+ tooltip?: string;
76
+ disabled?: boolean;
77
+ }
78
+ export interface ULToggleGroupProps {
79
+ /** "single" (one value, lens indicator) | "multiple" (aria-pressed per item). */ type?: 'single' | 'multiple'; /** Items ({ value, label?, icon?, disabled?, aria-label? }); icon-only items need aria-label. */
80
+ items: ToggleItem[];
81
+ /** Controlled value: string (single) or string[] (multiple). */ value?: string | string[]; /** Initial value when uncontrolled. */
82
+ defaultValue?: string | string[]; /** Called with the new value (string or string[] per type). */
83
+ onValueChange?: (v: string | string[]) => void;
84
+ /** "md" (default) | "sm". */ size?: 'sm' | 'md'; /** Disables the control (not focusable, dimmed). Default false. */
85
+ disabled?: boolean; /** Accessible name when there is no visible label. */
86
+ 'aria-label'?: string; /** Id of the element that labels the group. */
87
+ 'aria-labelledby'?: string; /** Extra class on the root element. */
88
+ className?: string; /** Single mode: show the lens bubble while pressing / dragging. Default true. */
89
+ lens?: boolean;
90
+ }
91
+ /** single = radio semantics + the shared lens selection (createLensSelect: one resting indicator, the same code as ULSegmentedControl).
92
+ * multiple = aria-pressed toggles, flat pressed paint per item (several pressed items cannot share one indicator). Roving tabindex in both. */
93
+ export declare function ULToggleGroup({ type, items, value, defaultValue, onValueChange, size, disabled, className, lens, ...aria }: ULToggleGroupProps): React.JSX.Element;
94
+ export interface ULItemProps extends ContextMenuProps<{
95
+ id?: string;
96
+ }> {
97
+ title: React.ReactNode;
98
+ description?: React.ReactNode;
99
+ media?: React.ReactNode;
100
+ meta?: React.ReactNode;
101
+ actions?: React.ReactNode;
102
+ /** interactive: the main area is a button (or a link with href) */
103
+ onClick?: () => void;
104
+ href?: string;
105
+ selectable?: boolean;
106
+ selected?: boolean;
107
+ onSelectedChange?: (s: boolean) => void;
108
+ /** lines of description before truncation (default 1; 0 = wrap) */
109
+ descriptionLines?: number;
110
+ variant?: 'plain' | 'outline' | 'muted';
111
+ size?: 'sm' | 'md';
112
+ disabled?: boolean;
113
+ id?: string;
114
+ className?: string;
115
+ style?: React.CSSProperties;
116
+ }
117
+ export declare function ULItem({ title, description, media, meta, actions, onClick, href, selectable, selected, onSelectedChange, descriptionLines, variant, size, disabled, id, className, style, ...ctx }: ULItemProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
118
+ export declare function ULItemGroup({ children, label, className }: {
119
+ children: React.ReactNode;
120
+ label?: string;
121
+ className?: string;
122
+ }): React.JSX.Element;
123
+ export interface ULCollapsibleProps {
124
+ title: React.ReactNode;
125
+ children: React.ReactNode;
126
+ open?: boolean;
127
+ defaultOpen?: boolean;
128
+ onOpenChange?: (o: boolean) => void;
129
+ disabled?: boolean;
130
+ trailing?: React.ReactNode;
131
+ id?: string;
132
+ className?: string;
133
+ style?: React.CSSProperties;
134
+ }
135
+ export declare function ULCollapsible({ title, children, open, defaultOpen, onOpenChange, disabled, trailing, id, className, style }: ULCollapsibleProps): React.JSX.Element;
136
+ /** Thumb maths (exported for tests): size and offset in px for one axis. */
137
+ export declare function scrollThumb(client: number, content: number, pos: number, track: number, min?: number): {
138
+ size: number;
139
+ offset: number;
140
+ visible: boolean;
141
+ };
142
+ export interface ULScrollAreaProps {
143
+ children: React.ReactNode;
144
+ axis?: 'y' | 'x' | 'both';
145
+ maxHeight?: number | string;
146
+ height?: number | string; /** accessible name: makes the viewport a focusable region (keyboard scrolling) */
147
+ label?: string;
148
+ shadows?: boolean;
149
+ overscroll?: 'auto' | 'contain';
150
+ className?: string;
151
+ style?: React.CSSProperties;
152
+ viewportRef?: React.MutableRefObject<HTMLDivElement | null>;
153
+ }
154
+ export declare function ULScrollArea({ children, axis, maxHeight, height, label, shadows, overscroll, className, style, viewportRef }: ULScrollAreaProps): React.JSX.Element;
@@ -0,0 +1,28 @@
1
+ import * as React from 'react';
2
+ import type { Accent } from '../../glass/accent.js';
3
+ import '../shared/lens.css';
4
+ import './ULTabs.css';
5
+ import { type ContextMenuProps } from '../ULContainers/contextTarget.js';
6
+ export interface TabItem {
7
+ value: string;
8
+ label: React.ReactNode;
9
+ content?: React.ReactNode;
10
+ disabled?: boolean;
11
+ icon?: React.ReactNode;
12
+ }
13
+ export interface ULTabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
14
+ /** Tabs ({ value, label, content?, icon?, disabled? }); a panel renders only for items with content. */ items: TabItem[];
15
+ /** Controlled selected tab value. */ value?: string;
16
+ /** Initial tab when uncontrolled. Default the first enabled tab. */ defaultValue?: string;
17
+ /** Called with the selected tab value (click, arrows, Home / End). */ onValueChange?: (v: string) => void;
18
+ /** "horizontal" (default) | "vertical"; arrow keys follow it. */ orientation?: 'horizontal' | 'vertical';
19
+ /** Lens bubble on press / drag / selection changes. Default true. */
20
+ lens?: boolean;
21
+ /** Accent colour: accent name ("violet", "ice", "emerald", "amber", "rose") or a CSS colour (checked by guardAccent). */ accent?: Accent;
22
+ /** Accessible name of the tab list. */
23
+ 'aria-label'?: string;
24
+ /** Panels mount lazily on first visit; keepMounted keeps visited panels mounted (hidden) instead of unmounting them. */
25
+ keepMounted?: boolean;
26
+ }
27
+ /** Tabs. contextMenu target: { component: 'tabs', kind: 'tab', id: value, data: TabItem } (tab headers only). */
28
+ export declare function ULTabs(props: ULTabsProps & ContextMenuProps<TabItem>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
@@ -0,0 +1,22 @@
1
+ export interface AnchoredTooltipOptions {
2
+ /** Element whose items get tooltips (events are delegated). */
3
+ container: HTMLElement;
4
+ /** Positioned ancestor the tooltip is laid out in. Must not clip it. */
5
+ layer: HTMLElement;
6
+ /** Item selector. Default: [data-ul-tip]. */
7
+ items?: string;
8
+ /** Tooltip text for an item. Default: its data-ul-tip attribute. */
9
+ text?: (el: HTMLElement) => string;
10
+ side?: 'top' | 'bottom' | 'right' | 'left';
11
+ /** Optional element the tooltip must clear (e.g. the popper the items live in). */
12
+ clear?: () => HTMLElement | null;
13
+ /** Hover delay in ms (keyboard focus shows immediately). Default 350. */
14
+ delay?: number;
15
+ }
16
+ export interface AnchoredTooltip {
17
+ readonly el: HTMLElement; /** Show for an item now (specs, tests). */
18
+ show(item: HTMLElement): void;
19
+ hide(): void;
20
+ destroy(): void;
21
+ }
22
+ export declare function createAnchoredTooltip(o: AnchoredTooltipOptions): AnchoredTooltip;
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Ready-made action components, all thin layers over the core (useAsyncAction + ULActionButton).
3
+ * Copy, Save (+ status, unsaved guard), Submit, Confirm (inline / hold / type), Download / Export, Refresh, Toggle icon,
4
+ * Share, Undo toast. Tooltips are the shared anchored tooltip; overlays are the existing ULMenu / ULModal / ULToast.
5
+ */
6
+ import * as React from 'react';
7
+ import type { LiveSource } from '../../live/liveSource.js';
8
+ import { ULActionButton, useAsyncAction, useActionTooltip, useCoalescedAction, actionText, announce, ACTION_CANCEL, type ULActionButtonProps, type ActionStatus, type CoalesceMode, type CoalescedStatus } from './core.js';
9
+ type Base = Omit<ULActionButtonProps, 'onAction'>;
10
+ /** Copies text (and optional HTML). Clipboard API first; hidden-textarea fallback when the API is missing, the context is
11
+ * insecure or permission is denied. Throws when both fail. Never logs the value. */
12
+ export declare function copyText(text: string, html?: string): Promise<void>;
13
+ export interface ULCopyButtonProps extends Omit<Base, 'onCopy' | 'value' | 'variant'> {
14
+ /** Text to copy, or a (async) function returning it at click time. Never logged or announced when `sensitive`. */ value: string | (() => string | Promise<string>);
15
+ /** Rich copy (text/html) where supported. */
16
+ html?: string | (() => string | Promise<string>);
17
+ /** Accessible / visible label. Default: localised ("Copy" in English). */ label?: string;
18
+ /** "button" (default, label + icon) | "icon" (icon only, needs label) | "inline" (plain, for text rows). */ variant?: 'icon' | 'button' | 'inline';
19
+ /** Button material. Default "glass" ("plain" for variant="inline" or inside ULInputGroup). */
20
+ buttonVariant?: 'primary' | 'secondary' | 'tinted' | 'plain';
21
+ /** Called with the copied text after a successful write. */ onCopy?: (text: string) => void;
22
+ /** Tooltip / announce text after success. Default: localised ("Copied to clipboard" in English). */ copiedLabel?: string;
23
+ /** Tooltip / announce text when the clipboard write fails. Default: localised ("Couldn't copy" in English). */ failedLabel?: string;
24
+ /** @internal tests: replace the clipboard writer. */
25
+ writer?: (text: string, html?: string) => Promise<void>;
26
+ }
27
+ export declare function ULCopyButton({ value, html, label, variant, buttonVariant, onCopy, copiedLabel, failedLabel, feedback, locale, sensitive, writer, ...rest }: ULCopyButtonProps): React.JSX.Element;
28
+ export interface ULSaveButtonProps extends Base {
29
+ /** Save handler; a returned promise drives loading → success / error (async action core). */ onSave: () => Promise<void> | void;
30
+ /** No unsaved changes: disabled (or hidden with hideWhenClean). Default true. */
31
+ dirty?: boolean;
32
+ /** Hide the button while `dirty` is false. Default false. */ hideWhenClean?: boolean;
33
+ /** Cmd / Ctrl + S runs the save (preventDefault). */
34
+ shortcut?: boolean;
35
+ /** Text for the error tooltip / live region. */
36
+ errorMessage?: (e: unknown) => string;
37
+ /** Idle label. Default: localised ("Save" in English). */ label?: string;
38
+ }
39
+ export declare function ULSaveButton({ onSave, dirty, hideWhenClean, shortcut, errorMessage, label, locale, ...rest }: ULSaveButtonProps): React.JSX.Element | null;
40
+ /** beforeunload while dirty, plus a router-agnostic check: call shouldBlock() before navigating. */
41
+ export declare function useUnsavedChangesGuard(dirty: boolean, o?: {
42
+ message?: string;
43
+ onBlock?: () => void;
44
+ }): {
45
+ shouldBlock: () => boolean;
46
+ };
47
+ export type SaveState = 'clean' | 'dirty' | 'saving' | 'saved' | 'error';
48
+ export interface ULSaveStatusProps {
49
+ status: SaveState; /** Time of the last save (ms epoch); shown as "Saved 2 min ago" via the shared ULTimeAgo timer. */
50
+ savedAt?: number | null; /** Shows a Retry link in the error state. */
51
+ onRetry?: () => void; /** "en" | "sk" | "de" | "cs". Default "en". */
52
+ locale?: string; /** Extra class on the status line. */
53
+ className?: string;
54
+ }
55
+ /** Quiet autosave indicator. Same icon / label swap cell, polite announcements on state changes (not on time ticks), no layout jump. */
56
+ export declare function ULSaveStatus({ status, savedAt, onRetry, locale, className }: ULSaveStatusProps): React.JSX.Element;
57
+ export interface ULSubmitButtonProps extends Omit<Base, 'onSubmit'> {
58
+ /** Controlled pending (the form library owns the request). */
59
+ pending?: boolean;
60
+ /** Or: the button submits through this promise (receives the form data; validation runs first). */
61
+ onSubmit?: (data: FormData | undefined, form: HTMLFormElement | null) => Promise<unknown> | unknown;
62
+ /** Form element to submit (when the button is outside the form). */ form?: string;
63
+ /** Idle label. Default: localised ("Submit" in English). */ label?: string;
64
+ }
65
+ export declare function ULSubmitButton({ pending, onSubmit, form, label, locale, ...rest }: ULSubmitButtonProps): React.JSX.Element;
66
+ export interface ULPublishButtonProps extends Base {
67
+ /** Publish handler (promise → loading / success / error). */ onPublish: () => Promise<unknown> | unknown;
68
+ /** Already published: the button offers Unpublish (secondary) when onUnpublish is given. */
69
+ published?: boolean;
70
+ /** Unpublish handler; when set the button toggles between the two states. */ onUnpublish?: () => Promise<unknown> | unknown;
71
+ }
72
+ export declare function ULPublishButton({ onPublish, published, onUnpublish, locale, ...rest }: ULPublishButtonProps): React.JSX.Element;
73
+ /** Type-to-confirm field (shared by ULConfirmAction type mode and ULAlertDialog). Match = trimmed value === text. */
74
+ export declare function ULTypeToConfirm({ text, value, onValueChange, locale }: {
75
+ text: string;
76
+ value: string;
77
+ onValueChange: (v: string) => void;
78
+ locale?: string;
79
+ }): React.JSX.Element;
80
+ export interface ULConfirmActionProps extends Base {
81
+ /** Confirmation style: "inline" (default, second click), "hold" (press and hold) or "type" (type-to-confirm dialog). */ confirm?: 'inline' | 'hold' | 'type';
82
+ /** Runs after confirmation; a promise drives loading / success / error. */ onConfirm: () => Promise<unknown> | unknown;
83
+ /** Idle label (e.g. "Delete"). */ label?: string;
84
+ /** Label while waiting for the confirmation (inline mode). Default: localised ("Confirm?" in English). */ confirmLabel?: string;
85
+ /** type mode: the text to type, dialog title / description. */
86
+ typeText?: string; /** Dialog title for confirm="type". */
87
+ title?: string; /** Dialog body for confirm="type". */
88
+ description?: React.ReactNode;
89
+ /** Hold duration for confirm="hold". Default --ul-action-hold-ms. */ holdMs?: number; /** Inline mode: time before the armed state resets. Default --ul-action-confirm-timeout. */
90
+ timeoutMs?: number;
91
+ }
92
+ export declare function ULConfirmAction({ confirm, onConfirm, label, confirmLabel, typeText, title, description, holdMs, timeoutMs, locale, ...rest }: ULConfirmActionProps): React.JSX.Element;
93
+ export type ExportResult = Blob | string;
94
+ export interface ULDownloadButtonProps extends Base {
95
+ /** Returns a Blob, a URL or text (the component never fetches by itself). report(p) for determinate progress 0..1. */
96
+ onExport: (o: {
97
+ format?: string;
98
+ report: (p: number) => void;
99
+ }) => ExportResult | Promise<ExportResult>;
100
+ /** File name, or a function of the chosen format. Default "download". */ filename?: string | ((format?: string) => string);
101
+ /** Controlled progress 0..1 (else onExport's report). */
102
+ progress?: number | null;
103
+ /** Offered formats ({ id, label }); more than one shows a format menu. */ formats?: {
104
+ id: string;
105
+ label: string;
106
+ }[];
107
+ /** Format used by a plain click. Default the first of `formats`. */ defaultFormat?: string;
108
+ /** Idle label. Default: localised ("Download" in English). */ label?: string;
109
+ }
110
+ export declare function ULDownloadButton({ onExport, filename, progress, formats, defaultFormat, label, locale, ...rest }: ULDownloadButtonProps): React.JSX.Element;
111
+ /** Same component with export wording. */
112
+ export declare function ULExportButton(props: ULDownloadButtonProps): React.JSX.Element;
113
+ export interface ULRefreshButtonProps extends Base {
114
+ /** Refresh handler (promise → spinner, then "Updated just now"). Clicks while running coalesce into one follow-up. */ onRefresh?: () => Promise<unknown> | unknown;
115
+ /** Last update time (controlled); else the last successful refresh. */
116
+ updatedAt?: number | null;
117
+ /** Show "Updated n min ago" next to the button. Default true. */ showUpdated?: boolean;
118
+ /** Auto refresh every n ms with a countdown ring; pauses while the tab is hidden. */
119
+ autoRefresh?: number;
120
+ /** Follow a live source: refresh = reconnect; "updated" follows its live status. */
121
+ source?: LiveSource | null;
122
+ /** Accessible label. Default: localised ("Refresh" in English). */ label?: string;
123
+ }
124
+ export declare function ULRefreshButton({ onRefresh, updatedAt, showUpdated, autoRefresh, source, label, locale, iconOnly, ...rest }: ULRefreshButtonProps): React.JSX.Element;
125
+ declare const KINDS: {
126
+ readonly favorite: "heart";
127
+ readonly like: "heart";
128
+ readonly star: "star";
129
+ readonly pin: "pin";
130
+ readonly bookmark: "bookmark";
131
+ readonly mute: "volume-x";
132
+ };
133
+ export interface ULToggleIconButtonProps extends Omit<Base, 'labels' | 'icons' | 'onStatusChange' | 'status'> {
134
+ /** Preset icon + labels: "star" (default) | "favorite" | "like" | "pin" | "bookmark" | "mute". */ kind?: keyof typeof KINDS;
135
+ /** Custom icon when off (overrides `kind`). */ icon?: React.ReactNode; /** Custom icon when on. */
136
+ iconOn?: React.ReactNode;
137
+ /** Controlled pressed state. */ pressed?: boolean; /** Initial pressed state when uncontrolled. Default false. */
138
+ defaultPressed?: boolean;
139
+ /** Called once with the final value after the clicks settle; a rejection rolls back. Not called when the final value equals the committed one. */
140
+ onPressedChange?: (next: boolean) => Promise<unknown> | unknown;
141
+ /** Accessible name (required, icon-only control). */ label: string; /** Tooltip / announce text when it turns on (e.g. "Starred"). */
142
+ labelOn?: string; /** Tooltip / announce text when it turns off. */
143
+ labelOff?: string;
144
+ /** useCoalescedAction mode: "trailing" (default, one commit after the quiet period) | "leading-trailing". */ coalesce?: CoalesceMode; /** Quiet period before the commit. Default --ul-action-debounce-ms. */
145
+ debounceMs?: number; /** Commit at the latest after this long of continuous clicking. Default --ul-action-debounce-max-wait-ms. */
146
+ maxWaitMs?: number;
147
+ /** Commit the pending value when the button loses focus. Default true. */
148
+ flushOnBlur?: boolean;
149
+ /** Called with "idle" | "pending" | "saving" | "error". */ onStatusChange?: (s: CoalescedStatus) => void;
150
+ /** flush() handle (forms, route changes). */
151
+ flushRef?: React.MutableRefObject<(() => void) | null>;
152
+ }
153
+ export declare function ULToggleIconButton({ kind, icon, iconOn, pressed, defaultPressed, onPressedChange, label, labelOn, labelOff, locale, coalesce, debounceMs, maxWaitMs, flushOnBlur, onStatusChange, flushRef, ...rest }: ULToggleIconButtonProps): React.JSX.Element;
154
+ export interface ULShareButtonProps extends Base {
155
+ url: string; /** Share sheet title (navigator.share). */
156
+ title?: string; /** Share sheet text (navigator.share). */
157
+ text?: string; /** Use navigator.share when available, else copy the link. Default true. */
158
+ preferNative?: boolean; /** Accessible / visible label. Default: localised ("Share" in English). */
159
+ label?: string;
160
+ }
161
+ export declare function ULShareButton({ url, title, text, preferNative, label, locale, ...rest }: ULShareButtonProps): React.JSX.Element;
162
+ export interface ULUndoToastProps {
163
+ open: boolean; /** Called with false when the toast closes (timeout, undo, Esc). */
164
+ onOpenChange?: (o: boolean) => void; /** Trigger the toast morphs from (anchored morph). */
165
+ anchorRef: React.RefObject<HTMLElement | null>; /** Toast text (e.g. "3 invoices archived"). */
166
+ message: React.ReactNode; /** Undo handler; a promise shows loading on the Undo button. */
167
+ onUndo: () => Promise<unknown> | unknown; /** Auto-close after this many ms (paused on hover / focus). Default 5000. */
168
+ duration?: number; /** Undo button label. Default: localised ("Undo" in English). */
169
+ undoLabel?: string; /** "en" | "sk" | "de" | "cs". Default "en". */
170
+ locale?: string;
171
+ }
172
+ /** ULToast with Undo and a countdown ring; the toast's own timer and the ring pause on hover / focus. */
173
+ export declare function ULUndoToast({ open, onOpenChange, anchorRef, message, onUndo, duration, undoLabel, locale }: ULUndoToastProps): React.JSX.Element;
174
+ export { ULActionButton, useAsyncAction, useActionTooltip, useCoalescedAction, actionText, announce, ACTION_CANCEL };
175
+ export type { ULActionButtonProps, ActionStatus };