@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/Button.svelte

@@ -1,199 +1,211 @@
-<svelte:options runes />
-
-<script module lang="ts">
-	import { TooltipContext } from '../Contexts/TooltipContext.svelte.js';
-	import { Delay } from '../Delay/Delay.js';
-	import { passthrough } from '../Helpers/Helpers.svelte.js';
-	import { Colour, ColourSet } from '../scss/colours.js';
-	import { Side } from '../Types/Internal/Side.js';
-	import { Size } from '../Types/Internal/Size.js';
-	import { Variant } from '../Types/Internal/Variant.js';
-	import { getContext } from 'svelte';
-	import type { ButtonProps } from './ButtonProps.js';
-	import Icon from './Icon.svelte';
-
-	const paddingSizesVertical: Record<Size, string> = {
-		[Size.Tiny]: '0.25rem',
-		[Size.Small]: '0.375rem',
-		[Size.MediumSmall]: '0.5rem',
-		// [Size.Medium]: '0.625rem',
-		[Size.Medium]: '0.90625rem',
-		[Size.MediumLarge]: '0.90625rem',
-		[Size.Large]: '0.925rem',
-		[Size.XLarge]: '1.0125rem',
-		[Size.DoubleXLarge]: '1.1rem',
-		[Size.TripleXLarge]: '1.2975rem',
-		[Size.FillWidth]: '0.75rem', // TODO decide
-		[Size.FillHeight]: '0' // TODO decide
-	};
-
-	// TODO alter the values for these if required
-	const paddingSizesHorizontal: Record<Size, string> = {
-		[Size.Tiny]: '0.4875rem',
-		[Size.Small]: '0.8rem',
-		[Size.MediumSmall]: '0.6625rem',
-		[Size.Medium]: '0.75rem',
-		[Size.MediumLarge]: '0.8375rem',
-		[Size.Large]: '0.925rem',
-		[Size.XLarge]: '1.0125rem',
-		[Size.DoubleXLarge]: '1.1rem',
-		[Size.TripleXLarge]: '1.2975rem',
-		[Size.FillWidth]: '0.75rem', // TODO decide
-		[Size.FillHeight]: '0.75rem' // TODO decide
-	};
-
-	// const fontSizes: Record<Size, string> = {
-	// 	[Size.Tiny]: '0.8rem',
-	// 	[Size.Small]: '0.85rem',
-	// 	[Size.MediumSmall]: '0.94rem',
-	// 	[Size.Medium]: '1rem',
-	// 	[Size.MediumLarge]: '1rem',
-	// 	[Size.Large]: '1.16rem',
-	// 	[Size.XLarge]: '1.32rem',
-	// 	[Size.DoubleXLarge]: '1.48rem',
-	// 	[Size.TripleXLarge]: '1.64rem',
-	// 	[Size.FillWidth]: '1rem', // TODO decide
-	// 	[Size.FillHeight]: '1rem' // TODO decide
-	// };
-
-	// TODO
-	const borderSizes: Record<Size, string> = {
-		[Size.Tiny]: '0.1875rem',
-		[Size.Small]: '0.1875rem',
-		[Size.MediumSmall]: '0.1875rem',
-		[Size.Medium]: '0.1875rem',
-		[Size.MediumLarge]: '0.1875rem',
-		[Size.Large]: '0.1875rem',
-		[Size.XLarge]: '0.1875rem',
-		[Size.DoubleXLarge]: '0.1875rem',
-		[Size.TripleXLarge]: '0.1875rem',
-		[Size.FillWidth]: '0.1875rem', // TODO decide
-		[Size.FillHeight]: '0.1875rem' // TODO decide
-	};
-
-	const iconColours: Record<ColourSet, Colour | undefined> = {
-		[ColourSet.Primary]: Colour['$ui-white'],
-		[ColourSet.CallToAction]: Colour['$ui-white'],
-		[ColourSet.Secondary]: undefined,
-		[ColourSet.Auxiliary]: undefined,
-		[ColourSet.Warning]: Colour['$error-border'],
-		[ColourSet.Error]: Colour['$error-border'],
-		[ColourSet.Info]: Colour['$error-border']
-	};
-</script>
-
-<script lang="ts">
-	const {
-		type = 'button',
-		variant = Variant.Default,
-		toggled = false,
-		iconLeft,
-		iconTop,
-		iconRight,
-		iconBottom,
-		nowrap = false,
-		side,
-		size = Size.Medium,
-		label,
-		colourSet = ColourSet.Secondary,
-		dashed = false,
-		disabled = false,
-		fullWidth = false,
-		onclick,
-		onfocus,
-		onblur,
-		children,
-		relative,
-		noninteractive
-	}: ButtonProps = $props();
-	const tooltipContext = getContext<TooltipContext>(TooltipContext.identifier);
-</script>
-
-<!-- title={label} -->
-<!-- style="--font-size: {fontSizes[
-		size
-	]};" -->
-<button
-	onmouseenter={(e) => {
-		if (label) {
-			const rect = (e.target as HTMLButtonElement).getBoundingClientRect();
-			tooltipContext.showTooltip({
-				text: label,
-				arrow: side ?? Side.Left,
-				delay: Delay.Default,
-				rect
-			});
-		}
-	}}
-	onmouseleave={() => {
-		if (label) {
-			tooltipContext.hideTooltip(label);
-		}
-	}}
-	class:noninteractive
-	class:relative
-	class:default={variant === Variant.Default}
-	class:card-inner={variant === Variant.CardInner}
-	class:card={variant === Variant.Card}
-	class:call-to-action={colourSet === ColourSet.CallToAction}
-	class:primary={colourSet === ColourSet.Primary}
-	class:secondary-colour={colourSet === ColourSet.Secondary}
-	class:secondary-variant={variant === Variant.Secondary}
-	class:warning={colourSet === ColourSet.Warning}
-	class:error={colourSet === ColourSet.Error}
-	class:info={colourSet === ColourSet.Info}
-	class:fill-height={size === Size.FillHeight}
-	class:fill-width={size === Size.FillWidth}
-	style="--fallback-padding-horizontal: {paddingSizesHorizontal[
-		size
-	]}; --fallback-padding-vertical: {paddingSizesVertical[size]}; --border-width: {borderSizes[
-		size
-	]};"
-	class:dashed
-	class:full-width={fullWidth}
-	class:toolbar={variant === Variant.Toolbar}
-	class:left={side === Side.Left}
-	class:right={side === Side.Right}
-	class:top={side === Side.Top}
-	class:bottom={side === Side.Bottom}
-	class:toggled
-	class:nowrap
-	{type}
-	aria-label={label}
-	{disabled}
-	onclick={(e) => {
-		// e.stopImmediatePropagation();
-		// if (dev) {
-		// 	// console.trace();
-		// }
-		if (label) {
-			tooltipContext.hideTooltip(label);
-		}
-		onclick?.(e);
-	}}
-	{onfocus}
-	{onblur}
-	onkeydown={passthrough}
->
-	<div class="icon-container">
-		{#if iconLeft}
-			<Icon {...iconLeft} colour={iconColours[colourSet]} size={iconLeft.size ?? size} />
-		{/if}
-		{#if iconTop}
-			<Icon {...iconTop} />
-		{/if}
-		{#if children}
-			<span>{@render children()}</span>
-		{/if}
-		{#if iconBottom}
-			<Icon {...iconBottom} />
-		{/if}
-		{#if iconRight}
-			<Icon {...iconRight} colour={iconColours[colourSet]} size={iconRight.size ?? size} />
-		{/if}
-	</div>
-</button>
-
+<svelte:options runes />
+
+<script
+	module
+	lang="ts"
+>
+	import { passthrough } from '../Helpers/Helpers.svelte.js';
+	import { useTooltip } from '../Helpers/useTooltip.svelte.js';
+	import { Colour, ColourSet } from '../scss/colours.js';
+	import { Side } from '../Types/Internal/Side.js';
+	import { Size } from '../Types/Internal/Size.js';
+	import { Variant } from '../Types/Internal/Variant.js';
+	import type { ButtonProps } from './ButtonProps.js';
+	import Icon from './Icon.svelte';
+
+	const paddingSizesVertical: Record<Size, string> = {
+		[Size.Tiny]: '0.25rem',
+		[Size.Small]: '0.375rem',
+		[Size.MediumSmall]: '0.5rem',
+		// [Size.Medium]: '0.625rem',
+		[Size.Medium]: '0.90625rem',
+		[Size.MediumLarge]: '0.90625rem',
+		[Size.Large]: '0.925rem',
+		[Size.XLarge]: '1.0125rem',
+		[Size.DoubleXLarge]: '1.1rem',
+		[Size.TripleXLarge]: '1.2975rem',
+		[Size.FillWidth]: '0.75rem', // TODO decide
+		[Size.FillHeight]: '0', // TODO decide
+	};
+
+	// TODO alter the values for these if required
+	const paddingSizesHorizontal: Record<Size, string> = {
+		[Size.Tiny]: '0.4875rem',
+		[Size.Small]: '0.8rem',
+		[Size.MediumSmall]: '0.6625rem',
+		[Size.Medium]: '0.75rem',
+		[Size.MediumLarge]: '0.8375rem',
+		[Size.Large]: '0.925rem',
+		[Size.XLarge]: '1.0125rem',
+		[Size.DoubleXLarge]: '1.1rem',
+		[Size.TripleXLarge]: '1.2975rem',
+		[Size.FillWidth]: '0.75rem', // TODO decide
+		[Size.FillHeight]: '0.75rem', // TODO decide
+	};
+
+	// const fontSizes: Record<Size, string> = {
+	// 	[Size.Tiny]: '0.8rem',
+	// 	[Size.Small]: '0.85rem',
+	// 	[Size.MediumSmall]: '0.94rem',
+	// 	[Size.Medium]: '1rem',
+	// 	[Size.MediumLarge]: '1rem',
+	// 	[Size.Large]: '1.16rem',
+	// 	[Size.XLarge]: '1.32rem',
+	// 	[Size.DoubleXLarge]: '1.48rem',
+	// 	[Size.TripleXLarge]: '1.64rem',
+	// 	[Size.FillWidth]: '1rem', // TODO decide
+	// 	[Size.FillHeight]: '1rem' // TODO decide
+	// };
+
+	// TODO
+	const borderSizes: Record<Size, string> = {
+		[Size.Tiny]: '0.1875rem',
+		[Size.Small]: '0.1875rem',
+		[Size.MediumSmall]: '0.1875rem',
+		[Size.Medium]: '0.1875rem',
+		[Size.MediumLarge]: '0.1875rem',
+		[Size.Large]: '0.1875rem',
+		[Size.XLarge]: '0.1875rem',
+		[Size.DoubleXLarge]: '0.1875rem',
+		[Size.TripleXLarge]: '0.1875rem',
+		[Size.FillWidth]: '0.1875rem', // TODO decide
+		[Size.FillHeight]: '0.1875rem', // TODO decide
+	};
+
+	const iconColours: Record<ColourSet, Colour | undefined> = {
+		[ColourSet.Primary]: Colour['$ui-white'],
+		[ColourSet.CallToAction]: Colour['$ui-white'],
+		[ColourSet.Secondary]: Colour['$ui-blue-14'],
+		[ColourSet.Auxiliary]: Colour['$font-primary'],
+		[ColourSet.Warning]: Colour['$error-border'],
+		[ColourSet.Error]: Colour['$error-border'],
+		[ColourSet.Info]: Colour['$primary-blue-13'],
+	};
+</script>
+
+<script lang="ts">
+	const {
+		type = 'button',
+		variant = Variant.Default,
+		toggled = false,
+		iconLeft,
+		iconTop,
+		iconRight,
+		iconBottom,
+		nowrap = false,
+		side,
+		size = Size.Medium,
+		label,
+		colourSet = ColourSet.Secondary,
+		dashed = false,
+		disabled = false,
+		fullWidth = false,
+		onclick,
+		onfocus,
+		onblur,
+		onkeydown: onkeydownProp,
+		children,
+		relative,
+		noninteractive,
+	}: ButtonProps = $props();
+	function onkeydown(e: KeyboardEvent): void {
+		passthrough(e);
+		if (document.activeElement === e.target) {
+			onkeydownProp?.(e);
+		}
+	}
+
+	// Shared tooltip lifecycle: hover handlers plus unmount-time teardown so
+	// a rapidly-churning host (toolbar, table row) does not leave the global
+	// tooltip host painting against a node that no longer exists. The helper
+	// also exposes an `onclick` hook that we compose with the consumer's
+	// `onclick`. The extra `$effect` dismisses the tooltip when `disabled`
+	// flips to true mid-hover - the disabled element will not fire its own
+	// `mouseleave`.
+	const tt = useTooltip({
+		text: () => label,
+		arrow: () => side ?? Side.Left,
+	});
+	$effect(() => {
+		if (disabled) {
+			tt.onmouseleave();
+		}
+	});
+</script>
+
+<!-- title={label} -->
+<!-- style="--font-size: {fontSizes[
+		size
+	]};" -->
+<button
+	onmouseenter={tt.onmouseenter}
+	onmouseleave={tt.onmouseleave}
+	class:noninteractive
+	class:relative
+	class:default={variant === Variant.Default}
+	class:card-inner={variant === Variant.CardInner}
+	class:card={variant === Variant.Card}
+	class:call-to-action={colourSet === ColourSet.CallToAction}
+	class:primary={colourSet === ColourSet.Primary}
+	class:secondary-colour={colourSet === ColourSet.Secondary}
+	class:secondary-variant={variant === Variant.Secondary}
+	class:warning={colourSet === ColourSet.Warning}
+	class:error={colourSet === ColourSet.Error}
+	class:info={colourSet === ColourSet.Info}
+	class:fill-height={size === Size.FillHeight}
+	class:fill-width={size === Size.FillWidth}
+	style="--fallback-padding-horizontal: {paddingSizesHorizontal[
+		size
+	]}; --fallback-padding-vertical: {paddingSizesVertical[size]}; --border-width: {borderSizes[
+		size
+	]};"
+	class:dashed
+	class:full-width={fullWidth}
+	class:toolbar={variant === Variant.Toolbar}
+	class:left={side === Side.Left}
+	class:right={side === Side.Right}
+	class:top={side === Side.Top}
+	class:bottom={side === Side.Bottom}
+	class:toggled
+	class:nowrap
+	{type}
+	aria-label={label}
+	{disabled}
+	onclick={(e) => {
+		tt.onclick();
+		onclick?.(e);
+	}}
+	{onfocus}
+	{onblur}
+	{onkeydown}
+>
+	<div class="icon-container">
+		{#if iconLeft}
+			<Icon
+				{...iconLeft}
+				colour={iconColours[colourSet]}
+				size={iconLeft.size ?? size}
+			/>
+		{/if}
+		{#if iconTop}
+			<Icon {...iconTop} />
+		{/if}
+		{#if children}
+			<span>{@render children()}</span>
+		{/if}
+		{#if iconBottom}
+			<Icon {...iconBottom} />
+		{/if}
+		{#if iconRight}
+			<Icon
+				{...iconRight}
+				colour={iconColours[colourSet]}
+				size={iconRight.size ?? size}
+			/>
+		{/if}
+	</div>
+</button>
+
 <style>.card {
   color: #3a4952;
   fill: #3a4952;
@@ -507,4 +519,4 @@ button.toolbar:not([disabled]).toggled.bottom {
 }
 button.toolbar:not([disabled]).toggled svg {
   fill: #259fc7;
-}</style>
+}</style>

package/dist/Components/ButtonProps.d.ts

@@ -4,26 +4,91 @@ import type { Size } from '../Types/Internal/Size.js';
 import type { Variant } from '../Types/Internal/Variant.js';
 import type { Snippet } from 'svelte';
 import type { PartialIconProps } from './PartialIconProps.js';
+/**
+ * Props for the foundational {@link Button} component. Every option is optional
+ * because Button is designed to be drop-in-friendly: a bare `<Button>Save</Button>`
+ * renders a secondary, medium-sized push button with no icon or tooltip.
+ */
 export interface ButtonProps {
+    /** Native `<button type>` attribute. Defaults to `'button'` so the button never
+     *  accidentally submits an enclosing form. */
     type?: 'button' | 'submit' | 'reset' | undefined;
+    /** Visual variant: default push button, card surface, inner card, toolbar, or secondary. */
     variant?: Variant | undefined;
+    /** Whether the button renders in its toggled (selected) visual state. */
     toggled?: boolean | undefined;
+    /**
+     * Icon rendered to the left of the label.
+     *
+     * NOTE: The four side props (`iconLeft`, `iconRight`, `iconTop`,
+     * `iconBottom`) are deliberately **not** mutually exclusive at the
+     * type level. Buttons that need icons on more than one side (for
+     * example, a "next" button with a directional chevron on the right
+     * and a status dot on the left) are well established in the design
+     * system. The discriminated-union alternative was evaluated and
+     * deferred (see `Concepts/ButtonIconSides` for the migration plan)
+     * because the type-safety gain is negligible compared with the
+     * breaking-change cost across every existing call site.
+     *
+     * If a single button passes more than one side prop, all of them
+     * render simultaneously. If you need an at-most-one constraint at a
+     * particular call site, enforce it locally with a discriminated
+     * helper before composing `<Button>`.
+     */
     iconLeft?: PartialIconProps | undefined;
+    /**
+     * Icon rendered above the label. See `iconLeft` for the rationale on
+     * why this is independently optional rather than part of a
+     * discriminated union.
+     */
     iconTop?: PartialIconProps | undefined;
+    /**
+     * Icon rendered to the right of the label. See `iconLeft` for the
+     * rationale on why this is independently optional rather than part
+     * of a discriminated union.
+     */
     iconRight?: PartialIconProps | undefined;
+    /**
+     * Icon rendered below the label. See `iconLeft` for the rationale on
+     * why this is independently optional rather than part of a
+     * discriminated union.
+     */
     iconBottom?: PartialIconProps | undefined;
+    /** Prevent the label from wrapping when the button is narrower than its content. */
     nowrap?: boolean | undefined;
+    /** Side of the trigger the tooltip arrow points from. Defaults to Side.Left. */
     side?: Side | undefined;
+    /** Sizing token controlling padding, font size, and border width. Defaults to Size.Medium. */
     size?: Size | undefined;
+    /** Render the border as a dashed outline. */
     dashed?: boolean | undefined;
+    /** Disable interaction. Sets the native `disabled` attribute and hides the tooltip. */
     disabled?: boolean | undefined;
+    /** Stretch the button to fill its container's inline axis. */
     fullWidth?: boolean | undefined;
-    label?: string | null | undefined;
+    /**
+     * Accessible name. Doubles as the tooltip text shown on hover. An
+     * empty string or `undefined` suppresses the tooltip and aria-label.
+     *
+     * BREAKING (vNext): the `null` variant has been removed. Pass
+     * `undefined` (or omit the prop) instead of `null` to indicate the
+     * absence of a label.
+     */
+    label?: string | undefined;
+    /** Semantic colour set used for foreground/background. Defaults to ColourSet.Secondary. */
     colourSet?: ColourSet | undefined;
+    /** Click handler. Tooltip is hidden synchronously before the handler fires. */
     onclick?: ((e: MouseEvent) => void) | undefined;
+    /** Native focus event handler. */
     onfocus?: ((e: FocusEvent) => void) | undefined;
+    /** Native blur event handler. */
     onblur?: ((e: FocusEvent) => void) | undefined;
+    /** Keydown handler. Composed with `passthrough` so scanner workflows continue to fire. */
+    onkeydown?: ((e: KeyboardEvent) => void) | undefined;
+    /** Snippet rendered between the optional icons. Typically the visible label. */
     children?: Snippet;
+    /** Apply `position: relative` so absolutely-positioned overlays anchor to the button. */
     relative?: boolean;
+    /** Visually present the button without interactive affordances (cursor stays at not-allowed). */
     noninteractive?: boolean;
 }