@luxalgo/vela 0.6.1 → 0.6.2

package/dist/ui.d.cts

@@ -14,6 +14,11 @@ declare function withAlpha(color: string, alpha: number): string;
 /** A ready-to-insert element rendering the icon (empty span when unknown). */
 declare function iconEl(id: string, doc?: Document): HTMLElement;
 
+/** Overlay scrollbar used by settings panes, dialog bodies, and similar chrome. */
+declare function overlayScrollbarCss(selector: string, width?: number): string;
+/** Focus ring shared by typeable fields (combo inputs, textareas). */
+declare const FIELD_FOCUS_CSS = "outline:none;transition:border-color .12s ease,box-shadow .12s ease;";
+declare const FIELD_FOCUS_RING = "border-color:var(--vela-focus);box-shadow:0 0 0 3px var(--vela-focus-soft);";
 /** Inject a stylesheet once per root (document or shadow root). Idempotent by id. */
 declare function injectStyles(id: string, css: string, root?: Document | ShadowRoot): void;
 
@@ -189,19 +194,36 @@ interface DialogOptions extends DialogControllerOptions {
      *  dialogs edit live content). Pass true for a dimming scrim; the backdrop still
      *  catches interact-outside dismissal either way. */
     dimBackdrop?: boolean;
+    /** Vertical placement of the card. Default `top` (current 10vh pad). */
+    align?: 'top' | 'center';
+    /** Pin the overlay to `host` (absolute) instead of the viewport (fixed). */
+    contained?: boolean;
+    /** Footer pinned below the scrollable body. */
+    footer?: Node | ((el: HTMLElement) => void);
+    /** Extra nodes before the title (e.g. a mobile section burger). */
+    headerStart?: Node;
+    /** Skip default body padding — the caller owns the body layout. */
+    flush?: boolean;
+    /** Extra class on the panel. */
+    className?: string;
+    /** Close when the backdrop itself is pressed (not when a portaled popover is). */
+    closeOnBackdrop?: boolean;
 }
 declare class Dialog {
     /** Caller-owned content area — append your form/panel here. */
     readonly body: HTMLElement;
-    private readonly backdrop;
-    private readonly positioner;
-    private readonly panel;
+    readonly panel: HTMLElement;
+    readonly titleEl: HTMLElement;
+    readonly positioner: HTMLElement;
+    readonly backdrop: HTMLElement;
+    readonly footer: HTMLElement | null;
     private readonly handle;
     private readonly ctrl;
     constructor(opts?: DialogOptions);
     get open(): boolean;
     show(): void;
     hide(): void;
+    contains(node: Node | null): boolean;
     destroy(): void;
 }
 
@@ -296,7 +318,7 @@ interface PlaceResult {
 }
 /** Inset a rectangle uniformly (positive inset shrinks). */
 declare function insetRect(r: Rect, inset: number): Rect;
-/** Viewport rect with a uniform inset (the 6px air ColorField/WidthField used). */
+/** Viewport rect with a uniform inset (the 6px air ColorField / glyph-select used). */
 declare function viewportRect(width: number, height: number, inset: number): Rect;
 /** Intersection of two rects. Empty (non-positive size) if they don't overlap. */
 declare function intersectRects(a: Rect, b: Rect): Rect;
@@ -342,6 +364,13 @@ interface PopoverOptions extends PopoverControllerOptions {
 declare function closeOpenPopovers(): void;
 declare function isPopoverOpen(): boolean;
 declare function openPopoverTrigger(): HTMLElement | null;
+/**
+ * True when this event already dismissed a popover on its way down — a dialog's
+ * outside-click close must swallow it instead of closing the dialog too (the popover
+ * hides itself on document CAPTURE, so by the time a backdrop listener runs,
+ * {@link isPopoverOpen} is already false).
+ */
+declare function eventDismissedPopover(e: Event): boolean;
 declare class Popover {
     readonly el: HTMLElement;
     readonly trigger: HTMLElement;
@@ -369,7 +398,7 @@ declare class Popover {
 }
 
 type SwitchSize = 'sm' | 'md';
-/** `bright` = indicator-dialog fill (`--vela-fg-bright`); `selected` = chart-settings fill. */
+/** `bright` = settings-dialog fill (`--vela-fg-bright`); `selected` = `--vela-selected-bg`. */
 type SwitchTone = 'bright' | 'selected';
 interface SwitchControllerOptions {
     checked?: boolean;
@@ -409,7 +438,7 @@ interface SelectControllerOptions {
     options: readonly SelectOption[];
     value?: string;
     size?: SelectSize;
-    /** Stretch the trigger to its parent (indicator dialog). Chart settings hug content. */
+    /** Stretch the trigger to its parent. Off: the shared 100px kit column (ellipsis). */
     fill?: boolean;
     disabled?: boolean;
     onChange?: (value: string, label: string) => void;
@@ -478,7 +507,9 @@ interface NumberInputControllerOptions {
     step?: number;
     integer?: boolean;
     size?: NumberSize;
-    /** `blur` (indicator dialog: clamp + steppers) vs `live` (chart settings: no clamp). */
+    /** `blur` clamps on commit (indicator dialog). `live` emits on every keystroke
+     *  (chart settings). Steppers default on for `blur`; pass `steppers: true` to
+     *  keep them with live commit. */
     commit?: NumberCommit;
     steppers?: boolean;
     clamp?: boolean;
@@ -518,6 +549,9 @@ interface NumberInputOptions extends NumberInputControllerOptions {
     placeholder?: string;
     emptyValue?: number;
     compact?: boolean;
+    /** Stretch to the parent. Defaults to on for `md`, off for `sm`. Chart settings
+     *  passes `false` so the field stays a 100px kit column instead of filling the pane. */
+    fill?: boolean;
 }
 declare class NumberInput {
     readonly el: HTMLElement;
@@ -607,8 +641,8 @@ interface ColorFieldOpts {
     id?: string;
     popover?: Pick<PopoverOptions, 'host' | 'position' | 'boundary' | 'zIndex' | 'gap' | 'align'>;
 }
-/** Closed-state swatch shape. `square` is the chart-settings field; `circle` is the
- *  indicator-dialog preview — a square chip inset from a matching square field border. */
+/** Closed-state swatch shape. `circle` is the settings-dialog preview (a square chip
+ *  inset from a matching field border); `square` is the compact drawing-chrome swatch. */
 declare function colorField(theme: VelaTheme, getVal: () => string, onVal: (v: string) => void, opts?: {
     shape?: ColorFieldShape;
     id?: string;
@@ -628,4 +662,217 @@ declare class ColorField {
 /** Close any open color (or other kit) popover — dialog teardown. */
 declare function closeColorPopover(): void;
 
-export { ColorField, type ColorFieldOpts, type ColorFieldShape, type ColorPickerController, type ColorPickerControllerOptions, Dialog, type DialogApi, type DialogControllerOptions, type DialogOptions, type DialogService, Drawer, type DrawerApi, type DrawerControllerOptions, type DrawerOptions, type DrawerService, type MachineHandle, Menu, type MenuApi, type MenuControllerOptions, type MenuItemDescriptor, type MenuOptions, type MenuService, type NumberCommit, NumberInput, type NumberInputController, type NumberInputControllerOptions, type NumberInputOptions, type NumberSize, type PlaceArgs, type PlaceResult, Popover, type PopoverAlign, type PopoverBoundary, type PopoverController, type PopoverControllerOptions, type PopoverOptions, type PopoverPosition, type Rect, Select, type SelectController, type SelectControllerOptions, type SelectListPopoverOpts, type SelectOption, type SelectOptions, type SelectSize, Switch, type SwitchController, type SwitchControllerOptions, type SwitchOptions, type SwitchSize, type SwitchTone, TextField, type TextFieldController, type TextFieldControllerOptions, type TextFieldOptions, type TextFieldSize, Tooltip, type TooltipApi, type TooltipControllerOptions, type TooltipOptions, type TooltipService, applyPlotOverlayTokens, applyThemeTokens, blendOver, buildColorPicker, buildPalette, clampNumber, closeColorPopover, closeOpenPopovers, colorField, colorPickerController, combineColor, decorateSelectScroll, dialogController, drawerController, ensureUIHost, fillSelectList, hslHex, iconEl, injectStyles, insetRect, intersectRects, isPopoverOpen, menuController, nextUid, numberInputController, openPopoverTrigger, openSelectList, placePopover, popoverController, runMachine, selectController, snapToStep, splitColor, switchController, textFieldController, toggleSelectList, tooltipController, transparencyChecker, viewportRect, withAlpha };
+type FieldGridVariant = 'settings' | 'inputs';
+type FieldLabelSize = 'sm' | 'md';
+/** Label↔control and between-row rhythm shared by the settings surfaces. */
+declare const FIELD_GAP_PX = 16;
+/** Grid tracks for a field grid. Settings hugs both columns; inputs give leftover
+ *  space to the control column. Mobile flips the label to a flexible track. */
+declare function fieldGridColumns(variant: FieldGridVariant, mobile: boolean): string;
+
+interface FieldGridOptions {
+    variant?: FieldGridVariant;
+    mobile?: boolean;
+}
+/** Shared label/control grid. Rows with `display:contents` participate in these tracks. */
+declare function fieldGrid(opts?: FieldGridOptions): HTMLElement;
+interface FieldSectionOptions {
+    variant?: FieldGridVariant;
+    first?: boolean;
+}
+/** Uppercase group heading that spans the field grid. */
+declare function fieldSection(title: string, opts?: FieldSectionOptions): HTMLElement;
+/** Vertical breathing space between row clusters. */
+declare function fieldSeparator(): HTMLElement;
+interface FieldToggleOpts {
+    checked: boolean;
+    onChange: (v: boolean) => void;
+    get?: () => boolean;
+    id?: string;
+}
+interface FieldInlineItem {
+    label?: string;
+    id?: string;
+    control: HTMLElement;
+    /** Toggle sits left of its label (bool companion on an inline row). */
+    toggleFirst?: boolean;
+    fit?: boolean;
+}
+interface FieldRowOptions {
+    label: string;
+    id?: string;
+    control?: HTMLElement | HTMLElement[];
+    info?: HTMLElement;
+    toggle?: FieldToggleOpts;
+    /** Full-width toggle + label (no control column). */
+    bool?: boolean;
+    /** Full-width stacked: centered label above a full-width control (textarea). */
+    stacked?: boolean;
+    /** Full-width wrap of several labeled controls. */
+    inline?: FieldInlineItem[];
+    /** Skip the 100px control wrap (color / session / time). */
+    fit?: boolean;
+    /** Wrap a single control at this width (indicator dialog number/select column). */
+    controlWidth?: number;
+    labelSize?: FieldLabelSize;
+    className?: string;
+}
+/** Label + control slot, optional master toggle, optional ⓘ. Grid-aware. */
+declare function fieldRow(opts: FieldRowOptions): HTMLElement;
+interface FieldControlHandle {
+    el: HTMLElement;
+    setValue?: (v: unknown) => void;
+}
+type FieldControlDesc = {
+    kind: 'number';
+    id?: string;
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    integer?: boolean;
+    commit?: 'blur' | 'live';
+    steppers?: boolean;
+    fill?: boolean;
+    compact?: boolean;
+    clamp?: boolean;
+    placeholder?: string;
+    emptyValue?: number;
+    title?: string;
+    onChange: (v: number) => void;
+    sync?: () => number;
+} | {
+    kind: 'select';
+    id?: string;
+    options: readonly SelectOption[];
+    value: string;
+    fill?: boolean;
+    theme?: VelaTheme;
+    list?: SelectListPopoverOpts;
+    title?: string;
+    onChange: (v: string) => void;
+    sync?: () => string;
+} | {
+    kind: 'switch';
+    id?: string;
+    checked: boolean;
+    onChange: (v: boolean) => void;
+    sync?: () => boolean;
+} | {
+    kind: 'color';
+    id?: string;
+    theme: VelaTheme;
+    get: () => string;
+    onChange: (v: string) => void;
+    popover?: ColorFieldOpts['popover'];
+    title?: string;
+} | {
+    kind: 'text';
+    id?: string;
+    value: string;
+    fill?: boolean;
+    placeholder?: string;
+    onChange: (v: string) => void;
+    sync?: () => string;
+} | {
+    kind: 'textarea';
+    id?: string;
+    value: string;
+    rows?: number;
+    autoGrow?: boolean;
+    maxLines?: number;
+    placeholder?: string;
+    onChange: (v: string) => void;
+    sync?: () => string;
+} | {
+    kind: 'width';
+    theme: VelaTheme;
+    get: () => number;
+    onChange: (v: number) => void;
+    title?: string;
+};
+/** One kit control from a neutral descriptor. `sync` re-reads on `vela-sync`. */
+declare function buildFieldControl(desc: FieldControlDesc): FieldControlHandle;
+
+type TextAreaSize = 'sm' | 'md';
+interface TextAreaControllerOptions {
+    value?: string;
+    size?: TextAreaSize;
+    rows?: number;
+    disabled?: boolean;
+    onChange?: (value: string) => void;
+}
+interface TextAreaController {
+    value: string;
+    size: TextAreaSize;
+    rows: number;
+    disabled: boolean;
+    commit(next: string): string | null;
+    sync(next: string): void;
+}
+declare function textAreaController(opts?: TextAreaControllerOptions): TextAreaController;
+
+interface TextAreaOptions extends TextAreaControllerOptions {
+    id?: string;
+    placeholder?: string;
+    /** Grow with content up to `maxLines`, then scroll. */
+    autoGrow?: boolean;
+    maxLines?: number;
+}
+declare class TextArea {
+    readonly el: HTMLElement;
+    readonly input: HTMLTextAreaElement;
+    private readonly ctrl;
+    private readonly autoGrow;
+    private readonly maxLines;
+    constructor(opts?: TextAreaOptions);
+    get value(): string;
+    setValue(v: string): void;
+    private grow;
+}
+
+interface GlyphOption<T extends string | number = string | number> {
+    value: T;
+    label: string;
+    /** Inner HTML of the preview glyph (currentColor stroke). */
+    glyph: string;
+}
+interface GlyphSelectControllerOptions<T extends string | number = string | number> {
+    options: readonly GlyphOption<T>[];
+    value: T;
+    onChange?: (value: T) => void;
+}
+interface GlyphSelectController<T extends string | number = string | number> {
+    options: readonly GlyphOption<T>[];
+    value: T;
+    setValue(v: T): void;
+    optionOf(value: T): GlyphOption<T> | undefined;
+    pick(value: T): T;
+}
+declare function glyphSelectController<T extends string | number>(opts: GlyphSelectControllerOptions<T>): GlyphSelectController<T>;
+/** The classic 1–5 px line-width ladder. */
+declare const WIDTH_FIELD_OPTIONS: readonly number[];
+/** A horizontal line glyph whose stroke IS the previewed weight. */
+declare function lineWidthGlyph(width: number): string;
+declare function widthFieldOptions(): readonly GlyphOption<number>[];
+
+interface GlyphSelectOptions<T extends string | number = string | number> extends GlyphSelectControllerOptions<T> {
+    theme: VelaTheme;
+    title?: string;
+    get?: () => T;
+}
+declare class GlyphSelect<T extends string | number = string | number> {
+    readonly el: HTMLButtonElement;
+    private readonly ctrl;
+    private readonly theme;
+    private readonly get;
+    constructor(opts: GlyphSelectOptions<T>);
+    setValue(v: T): void;
+    private paint;
+    private toggle;
+}
+/** Settings-dialog line-width field (1–5 px glyphs). */
+declare function widthField(theme: VelaTheme, getVal: () => number, onVal: (v: number) => void): HTMLElement;
+declare function closeWidthPopover(): void;
+
+export { ColorField, type ColorFieldOpts, type ColorFieldShape, type ColorPickerController, type ColorPickerControllerOptions, Dialog, type DialogApi, type DialogControllerOptions, type DialogOptions, type DialogService, Drawer, type DrawerApi, type DrawerControllerOptions, type DrawerOptions, type DrawerService, FIELD_FOCUS_CSS, FIELD_FOCUS_RING, FIELD_GAP_PX, type FieldControlDesc, type FieldControlHandle, type FieldGridOptions, type FieldGridVariant, type FieldInlineItem, type FieldLabelSize, type FieldRowOptions, type FieldSectionOptions, type FieldToggleOpts, type GlyphOption, GlyphSelect, type GlyphSelectController, type GlyphSelectControllerOptions, type GlyphSelectOptions, type MachineHandle, Menu, type MenuApi, type MenuControllerOptions, type MenuItemDescriptor, type MenuOptions, type MenuService, type NumberCommit, NumberInput, type NumberInputController, type NumberInputControllerOptions, type NumberInputOptions, type NumberSize, type PlaceArgs, type PlaceResult, Popover, type PopoverAlign, type PopoverBoundary, type PopoverController, type PopoverControllerOptions, type PopoverOptions, type PopoverPosition, type Rect, Select, type SelectController, type SelectControllerOptions, type SelectListPopoverOpts, type SelectOption, type SelectOptions, type SelectSize, Switch, type SwitchController, type SwitchControllerOptions, type SwitchOptions, type SwitchSize, type SwitchTone, TextArea, type TextAreaController, type TextAreaControllerOptions, type TextAreaOptions, type TextAreaSize, TextField, type TextFieldController, type TextFieldControllerOptions, type TextFieldOptions, type TextFieldSize, Tooltip, type TooltipApi, type TooltipControllerOptions, type TooltipOptions, type TooltipService, WIDTH_FIELD_OPTIONS, applyPlotOverlayTokens, applyThemeTokens, blendOver, buildColorPicker, buildFieldControl, buildPalette, clampNumber, closeColorPopover, closeOpenPopovers, closeWidthPopover, colorField, colorPickerController, combineColor, decorateSelectScroll, dialogController, drawerController, ensureUIHost, eventDismissedPopover, fieldGrid, fieldGridColumns, fieldRow, fieldSection, fieldSeparator, fillSelectList, glyphSelectController, hslHex, iconEl, injectStyles, insetRect, intersectRects, isPopoverOpen, lineWidthGlyph, menuController, nextUid, numberInputController, openPopoverTrigger, openSelectList, overlayScrollbarCss, placePopover, popoverController, runMachine, selectController, snapToStep, splitColor, switchController, textAreaController, textFieldController, toggleSelectList, tooltipController, transparencyChecker, viewportRect, widthField, widthFieldOptions, withAlpha };