@makolabs/ripple 2.5.9 → 3.0.0

package/dist/layout/sidebar/Sidebar.svelte

@@ -12,15 +12,46 @@
 	});
 	setContext('menubar', menubar);
 
-	// Track screen size for responsive behavior
-	let isSmallScreen = $state(false);
+	// Track screen size for responsive behavior.
+	// `isSmallScreen`: below xl (1280px) → auto-collapse to icon rail.
+	// `isMobile`: below md (768px) → sidebar slides in as a fixed overlay
+	// instead of taking a permanent column.
+	//
+	// Initialised via `matchMedia` inside the `$state` expression so the
+	// client-side first render already has the correct value — avoids the
+	// flash where mobile viewports would briefly show the desktop layout
+	// before onMount runs. On SSR both resolve to `false`; the CSS below
+	// uses `md:` / `max-md:` modifiers to hide the drawer regardless so
+	// the SSR output doesn't paint a w-64 column on narrow viewports.
+	function matchMediaOrFalse(query: string): boolean {
+		return typeof window !== 'undefined' && window.matchMedia(query).matches;
+	}
+	let isSmallScreen = $state(matchMediaOrFalse('(max-width: 1279.98px)'));
+	let isMobile = $state(matchMediaOrFalse('(max-width: 767.98px)'));
+
+	// Track previous viewport class so we only force-close the drawer
+	// when transitioning INTO mobile from a larger viewport. Without this,
+	// a minor resize on mobile (soft keyboard, orientation change) would
+	// unexpectedly close an already-open drawer.
+	let wasMobile = isMobile;
 
 	function updateCollapseState() {
 		if (typeof window !== 'undefined') {
-			isSmallScreen = window.innerWidth < 1280; // xl breakpoint
-			if (isSmallScreen && !menubar.collapsed) {
+			isSmallScreen = window.innerWidth < 1280;
+			const nextIsMobile = window.innerWidth < 768;
+			// Keep legacy auto-collapse on md-xl only — below md we fully
+			// hide via translate, so don't force the icon-rail state.
+			if (isSmallScreen && !nextIsMobile && !menubar.collapsed) {
 				menubar.collapsed = true;
 			}
+			if (nextIsMobile && !wasMobile) {
+				// Transitioning into mobile: close the drawer so it doesn't
+				// cover the app. Subsequent resizes on mobile won't re-close
+				// an open drawer.
+				menubar.collapsed = true;
+			}
+			isMobile = nextIsMobile;
+			wasMobile = nextIsMobile;
 		}
 	}
 
@@ -34,6 +65,10 @@
 		menubar.collapsed = !menubar.collapsed;
 	}
 
+	function openMobile() {
+		menubar.collapsed = false;
+	}
+
 	/**
 	 * Process a navigation item to determine if it should be active
 	 */
@@ -73,11 +108,19 @@
 
 	const sidebarClasses = $derived(
 		clsx(
-			`min-h-screen flex flex-col bg-gradient-to-b from-default-900 to-default-900 h-full shrink-0`,
-			{
-				'w-16': menubar.collapsed,
-				'w-64': !menubar.collapsed
-			}
+			`flex flex-col bg-gradient-to-b from-default-900 to-default-900 overflow-hidden`,
+			'transition-[width,transform] duration-300 ease-out',
+			// Mobile drawer mode: fixed overlay that slides in from the left.
+			// Full-width drawer (w-64), translates off-screen when collapsed.
+			// `isMobile` is initialised synchronously via matchMedia above so
+			// the client-side first render already picks the right branch,
+			// minimising the hydration flash.
+			isMobile && 'fixed inset-y-0 left-0 z-50 w-64 shadow-2xl',
+			isMobile && menubar.collapsed && '-translate-x-full',
+			// Desktop / tablet: normal flow, collapses to an icon rail.
+			!isMobile && 'min-h-screen h-full shrink-0',
+			!isMobile && menubar.collapsed && 'w-16',
+			!isMobile && !menubar.collapsed && 'w-64'
 		)
 	);
 
@@ -92,14 +135,47 @@
 	);
 </script>
 
+{#if menubar.collapsed}
+	<!-- Floating hamburger trigger: only needed on mobile when the drawer
+	     is closed. `md:hidden` keeps it mobile-only without needing a JS
+	     viewport check, which avoids a first-paint flash. -->
+	<button
+		type="button"
+		onclick={openMobile}
+		class="bg-default-900 fixed top-4 left-4 z-40 flex size-10 cursor-pointer items-center justify-center rounded-lg text-white shadow-lg md:hidden"
+		aria-label="Open navigation"
+		data-testid={buildTestId('sidebar', 'mobile-trigger', testId)}
+	>
+		{@render ToggleIcon('size-5')}
+	</button>
+{:else}
+	<!-- Backdrop: tap-to-close. Also `md:hidden` so desktop doesn't get
+	     covered by a full-viewport click-catcher. -->
+	<button
+		type="button"
+		onclick={toggle}
+		aria-label="Close navigation"
+		class="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm md:hidden"
+	></button>
+{/if}
+
 <div class={sidebarClasses} data-testid={buildTestId('sidebar', undefined, testId)}>
 	<div class={logoWrapperClasses}>
 		<div class="flex items-center gap-x-1">
 			{#if logo.src && !menubar.collapsed}
 				<img src={logo.src} alt={logo.title} class="size-8 shrink-0" />
 			{/if}
-			{#if logo.title && !menubar.collapsed}
-				<h1 class="text-xl font-bold text-white">{logo.title}</h1>
+			{#if logo.title}
+				<h1
+					class="overflow-hidden text-xl font-bold whitespace-nowrap text-white transition-all duration-200 ease-out"
+					class:max-w-0={menubar.collapsed}
+					class:opacity-0={menubar.collapsed}
+					class:max-w-xs={!menubar.collapsed}
+					class:opacity-100={!menubar.collapsed}
+					aria-hidden={menubar.collapsed}
+				>
+					{logo.title}
+				</h1>
 			{/if}
 		</div>
 		<button

package/dist/layout/sidebar/sidebar-types.d.ts

@@ -1,54 +1,113 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { Snippet } from 'svelte';
 import type { Component } from 'svelte';
+/** Collapse state passed to sidebar snippets. */
 export type MenuBar = {
     collapsed: boolean;
 };
+/** Shared fields for any named navigation entry. */
 export interface BaseNavigationItem {
     label: string;
 }
+/** Mixin for entries that can render a leading icon. */
 export interface WithIcon {
     Icon?: Component;
 }
+/** Mixin for entries that can show an "active" (current route) state. */
 export interface Activatable {
     active?: boolean;
 }
+/**
+ * Standard clickable link in the sidebar. Most sidebars are built from
+ * a mix of these plus `ParentItem`s (groups) and `DividerItem`s (rules).
+ */
 export interface LinkItem extends BaseNavigationItem, WithIcon, Activatable {
     href: string;
+    /** Short text rendered to the right of the label (e.g. count, shortcut). */
     meta?: string;
     /**
      * When true, the link will be active if the current route starts with this href.
-     * Example: href="/tushar" will be active for "/tushar/overview" and "/tushar/profile"
+     * Example: `href="/tushar"` will be active for `"/tushar/overview"` and `"/tushar/profile"`
      * @default false
      */
     matchPartial?: boolean;
 }
+/**
+ * Collapsible group with child links. Active when any descendant link
+ * matches the current route.
+ */
 export interface ParentItem extends BaseNavigationItem, Activatable {
     children: LinkItem[];
 }
+/** Horizontal separator between sections. */
 export interface DividerItem {
     type: 'horizontal-divider';
 }
+/** Union of everything that can appear in `SidebarProps.items`. */
 export type NavigationItem = LinkItem | ParentItem | DividerItem;
+/** Logo configuration rendered at the top of the sidebar. */
 export type LogoType = {
+    /** Image path. Omit for a text-only wordmark. */
     src?: string;
+    /** Wordmark shown next to (or instead of) the image. */
     title: string;
 };
+/**
+ * Props for `<NavGroup>` — a collapsible group of nav items. Usually
+ * consumed via `<Sidebar>`'s `items` prop, but exposed for custom
+ * compositions.
+ */
 export interface NavGroupProps {
+    /** Header snippet — receives `(label, meta)` from the parent. */
     labelArea: Snippet<[string, string]>;
+    /** Whether the group is currently "open" (expanded). */
     active?: boolean;
     children?: Snippet;
     class?: ClassValue;
     testId?: string;
 }
+/**
+ * Props for `<NavItem>` — a single navigation link. Usually consumed via
+ * `<Sidebar>`, but exposed for custom navigation compositions.
+ */
 export interface NavItemProps {
     href: string;
     active?: boolean;
+    /** Item content — receives a class value so custom children can style consistently. */
     children: Snippet<[ClassValue]>;
     class?: ClassValue;
     testId?: string;
 }
+/**
+ * Props for `<Sidebar>` — a left-rail navigation. Supports collapse
+ * (icon-only), nested groups, dividers, and custom below-logo / footer
+ * snippets (for market selectors, user menus, etc.).
+ *
+ * @example
+ * ```svelte
+ * <Sidebar
+ *   logo={{ src: '/logo.svg', title: 'Clark' }}
+ *   items={[
+ *     { label: 'Dashboard', href: '/', Icon: HomeIcon, matchPartial: false },
+ *     { label: 'Reports', href: '/reports', Icon: ReportIcon, matchPartial: true },
+ *     { type: 'horizontal-divider' },
+ *     {
+ *       label: 'Admin',
+ *       children: [
+ *         { label: 'Users', href: '/admin/users', Icon: UsersIcon },
+ *         { label: 'Billing', href: '/admin/billing', Icon: BillIcon }
+ *       ]
+ *     }
+ *   ]}
+ * >
+ *   {#snippet footer({ collapsed })}
+ *     <UserMenu compact={collapsed} />
+ *   {/snippet}
+ * </Sidebar>
+ * ```
+ */
 export interface SidebarProps {
+    /** Navigation items in render order. */
     items?: NavigationItem[];
     logo: LogoType;
     /** Optional snippet between the logo row and the navigation (receives collapse state) */

package/dist/layout/stepper/Stepper.svelte

@@ -0,0 +1,288 @@
+<script lang="ts">
+	import { cn } from '../../helper/cls.js';
+	import { buildTestId } from '../../helper/testid.js';
+	import Button from '../../button/Button.svelte';
+	import { Color } from '../../variants.js';
+	import type { StepperProps, StepState, StepperStep } from './stepper-types.js';
+
+	let {
+		steps,
+		currentStep = $bindable(0),
+		orientation = 'horizontal',
+		color = Color.PRIMARY,
+		clickableCompleted = true,
+		showNav = true,
+		backLabel = 'Back',
+		nextLabel = 'Next',
+		finishLabel = 'Finish',
+		content,
+		onfinish,
+		onchange,
+		responsive = true,
+		class: className = '',
+		testId
+	}: StepperProps = $props();
+
+	function stateFor(index: number, step: StepperStep): StepState {
+		if (step.state) return step.state;
+		if (index < safeStep) return 'complete';
+		if (index === safeStep) return 'active';
+		return 'upcoming';
+	}
+
+	// Clamp `currentStep` to valid bounds so an out-of-range bound value
+	// (or a parent that shrinks `steps`) can't leave us with an undefined
+	// `activeStep` while `canAdvance` reports true. Empty `steps` resolves
+	// to 0, which `steps[0]` tolerates (returns undefined handled below).
+	const safeStep = $derived(
+		steps.length === 0 ? 0 : Math.min(Math.max(currentStep, 0), steps.length - 1)
+	);
+
+	const activeStep = $derived(steps[safeStep]);
+	const isLast = $derived(safeStep === steps.length - 1);
+	const canAdvance = $derived(!!activeStep && !(activeStep.disabled ?? false));
+	const canGoBack = $derived(safeStep > 0);
+
+	// Fire `onchange` whenever the effective step index changes from any
+	// source — parent updates, `safeStep` clamping after `steps` shrinks,
+	// or our own `goTo()`. Docs promise "from any source", so handling it
+	// once here (instead of only inside `goTo`) keeps that contract.
+	let lastReportedStep: number | undefined = undefined;
+	$effect(() => {
+		if (lastReportedStep === undefined) {
+			lastReportedStep = safeStep;
+			return;
+		}
+		if (safeStep !== lastReportedStep) {
+			lastReportedStep = safeStep;
+			onchange?.(safeStep);
+		}
+	});
+
+	function goTo(index: number) {
+		if (index < 0 || index >= steps.length) return;
+		if (index === currentStep) return;
+		currentStep = index;
+		// `onchange` fires via the effect above.
+	}
+
+	function handleMarkerClick(index: number, state: StepState) {
+		// Require both `clickableCompleted` and `index < safeStep` so a
+		// consumer-supplied `state: 'complete'` on a future step can't
+		// unlock forward navigation — only backward jumps are allowed.
+		if (index < safeStep && state === 'complete' && clickableCompleted) goTo(index);
+	}
+
+	function handleNext() {
+		if (!canAdvance) return;
+		if (isLast) {
+			onfinish?.();
+			return;
+		}
+		goTo(safeStep + 1);
+	}
+
+	function handleBack() {
+		if (!canGoBack) return;
+		goTo(safeStep - 1);
+	}
+
+	const colorClasses = $derived(
+		{
+			[Color.DEFAULT]: { bg: 'bg-default-600', ring: 'ring-default-600', text: 'text-default-600' },
+			[Color.PRIMARY]: { bg: 'bg-primary-500', ring: 'ring-primary-500', text: 'text-primary-600' },
+			[Color.SECONDARY]: {
+				bg: 'bg-secondary-500',
+				ring: 'ring-secondary-500',
+				text: 'text-secondary-600'
+			},
+			[Color.INFO]: { bg: 'bg-info-500', ring: 'ring-info-500', text: 'text-info-600' },
+			[Color.SUCCESS]: { bg: 'bg-success-500', ring: 'ring-success-500', text: 'text-success-600' },
+			[Color.WARNING]: { bg: 'bg-warning-500', ring: 'ring-warning-500', text: 'text-warning-600' },
+			[Color.DANGER]: { bg: 'bg-danger-500', ring: 'ring-danger-500', text: 'text-danger-600' }
+		}[color]
+	);
+
+	function markerClass(state: StepState): string {
+		// `[&_svg]:size-4` constrains consumer-provided icon components so
+		// they match the built-in checkmark (size-4) inside the size-8 circle.
+		const base =
+			'flex size-8 items-center justify-center rounded-full border text-sm font-semibold transition-colors [&_svg]:size-4';
+		if (state === 'complete') return `${base} ${colorClasses.bg} border-transparent text-white`;
+		if (state === 'active')
+			return `${base} ${colorClasses.text} bg-white ring-2 ring-offset-2 ${colorClasses.ring} border-transparent`;
+		if (state === 'error') return `${base} bg-danger-500 border-transparent text-white`;
+		return `${base} border-default-300 bg-white text-default-400`;
+	}
+
+	function connectorBg(index: number): string {
+		return index < safeStep ? colorClasses.bg : 'bg-default-200';
+	}
+
+	// When responsive, the full list hides below `sm` and the compact
+	// indicator takes its place. Vertical doesn't need this — it already
+	// fits narrow viewports.
+	const horizontalListClass = $derived(
+		cn('flex flex-row items-start', responsive && 'hidden sm:flex')
+	);
+</script>
+
+<div
+	class={cn('flex flex-col gap-4', className)}
+	data-testid={buildTestId('stepper', undefined, testId)}
+>
+	{#if orientation === 'horizontal'}
+		{#if responsive}
+			<!-- Compact indicator: dots + "Step X of Y · Label", shown only below sm. -->
+			<div
+				class="flex items-center gap-3 sm:hidden"
+				data-testid={buildTestId('stepper', 'compact', testId)}
+			>
+				<div class="flex items-center gap-1.5" aria-hidden="true">
+					{#each steps as _s, i (i)}
+						<span
+							class={cn(
+								'size-2 rounded-full transition-colors',
+								i < safeStep
+									? colorClasses.bg
+									: i === safeStep
+										? cn(colorClasses.bg, 'ring-2 ring-offset-1', colorClasses.ring)
+										: 'bg-default-200'
+							)}
+						></span>
+					{/each}
+				</div>
+				{#if activeStep}
+					<span class="text-default-800 text-sm font-medium">
+						Step {safeStep + 1} of {steps.length}: {activeStep.label}
+					</span>
+				{/if}
+			</div>
+		{/if}
+
+		<ol class={horizontalListClass} aria-label="Progress">
+			{#each steps as step, i (step.label + i)}
+				{@const state = stateFor(i, step)}
+				{@const canClick = i < safeStep && state === 'complete' && clickableCompleted}
+				{@const notLast = i < steps.length - 1}
+				<li class="flex flex-1 items-start last:flex-none">
+					<div class="flex flex-col items-center gap-2">
+						<button
+							type="button"
+							class={cn(markerClass(state), canClick && 'cursor-pointer hover:brightness-95')}
+							disabled={!canClick}
+							aria-current={state === 'active' ? 'step' : undefined}
+							aria-label={step.label}
+							onclick={() => handleMarkerClick(i, state)}
+						>
+							{#if state === 'complete'}
+								<svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+									<path
+										fill-rule="evenodd"
+										d="M16.704 5.295a1 1 0 0 1 .001 1.414l-7.5 7.516a1 1 0 0 1-1.414 0l-3.5-3.5a1 1 0 1 1 1.414-1.414l2.793 2.793 6.793-6.809a1 1 0 0 1 1.414 0z"
+										clip-rule="evenodd"
+									/>
+								</svg>
+							{:else if step.icon}
+								{@const Icon = step.icon}
+								<Icon />
+							{:else}
+								{i + 1}
+							{/if}
+						</button>
+						<div class="flex flex-col text-center">
+							<span
+								class={cn(
+									'text-sm font-medium',
+									state === 'upcoming' ? 'text-default-500' : 'text-default-800'
+								)}
+							>
+								{step.label}
+							</span>
+							{#if step.description}
+								<span class="text-default-500 text-xs">{step.description}</span>
+							{/if}
+						</div>
+					</div>
+					{#if notLast}
+						<!-- mt-4 = half the size-8 marker so the line centres on the circle. -->
+						<div
+							class={cn('mx-2 mt-4 h-0.5 flex-1 transition-colors', connectorBg(i))}
+							aria-hidden="true"
+						></div>
+					{/if}
+				</li>
+			{/each}
+		</ol>
+	{:else}
+		<!-- Vertical: marker column owns the connector so flex-1 stretches it to the next marker. -->
+		<ol class="flex flex-col" aria-label="Progress">
+			{#each steps as step, i (step.label + i)}
+				{@const state = stateFor(i, step)}
+				{@const canClick = i < safeStep && state === 'complete' && clickableCompleted}
+				{@const notLast = i < steps.length - 1}
+				<li class="flex items-stretch gap-3">
+					<div class="flex flex-col items-center">
+						<button
+							type="button"
+							class={cn(markerClass(state), canClick && 'cursor-pointer hover:brightness-95')}
+							disabled={!canClick}
+							aria-current={state === 'active' ? 'step' : undefined}
+							aria-label={step.label}
+							onclick={() => handleMarkerClick(i, state)}
+						>
+							{#if state === 'complete'}
+								<svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+									<path
+										fill-rule="evenodd"
+										d="M16.704 5.295a1 1 0 0 1 .001 1.414l-7.5 7.516a1 1 0 0 1-1.414 0l-3.5-3.5a1 1 0 1 1 1.414-1.414l2.793 2.793 6.793-6.809a1 1 0 0 1 1.414 0z"
+										clip-rule="evenodd"
+									/>
+								</svg>
+							{:else if step.icon}
+								{@const Icon = step.icon}
+								<Icon />
+							{:else}
+								{i + 1}
+							{/if}
+						</button>
+						{#if notLast}
+							<div
+								class={cn('my-2 w-0.5 flex-1 transition-colors', connectorBg(i))}
+								aria-hidden="true"
+							></div>
+						{/if}
+					</div>
+					<div class={cn('flex flex-col pt-0.5', notLast && 'pb-6')}>
+						<span
+							class={cn(
+								'text-sm font-medium',
+								state === 'upcoming' ? 'text-default-500' : 'text-default-800'
+							)}
+						>
+							{step.label}
+						</span>
+						{#if step.description}
+							<span class="text-default-500 text-xs">{step.description}</span>
+						{/if}
+					</div>
+				</li>
+			{/each}
+		</ol>
+	{/if}
+
+	{#if content && activeStep}
+		<div data-testid={buildTestId('stepper', 'content', testId)}>
+			{@render content(safeStep, activeStep)}
+		</div>
+	{/if}
+
+	{#if showNav}
+		<div class="flex items-center justify-between">
+			<Button variant="outline" onclick={handleBack} disabled={!canGoBack}>{backLabel}</Button>
+			<Button {color} onclick={handleNext} disabled={!canAdvance}>
+				{isLast ? finishLabel : nextLabel}
+			</Button>
+		</div>
+	{/if}
+</div>

package/dist/layout/stepper/Stepper.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { StepperProps } from './stepper-types.js';
+declare const Stepper: import("svelte").Component<StepperProps, {}, "currentStep">;
+type Stepper = ReturnType<typeof Stepper>;
+export default Stepper;

package/dist/layout/stepper/stepper-types.d.ts

@@ -0,0 +1,80 @@
+import type { ClassValue } from 'tailwind-variants';
+import type { Snippet } from 'svelte';
+import type { Component } from 'svelte';
+import type { VariantColors } from '../../index.js';
+export type StepperStep = {
+    /** Short title shown under the step marker. */
+    label: string;
+    /** Optional sub-label (e.g. "3 min"). */
+    description?: string;
+    /**
+     * Optional icon rendered inside the marker instead of a number. Falls
+     * back to the index when omitted.
+     */
+    icon?: Component;
+    /**
+     * Explicit state override. When omitted, state is derived from
+     * `currentStep`:
+     * - index < currentStep → `'complete'`
+     * - index === currentStep → `'active'`
+     * - index > currentStep → `'upcoming'`
+     */
+    state?: StepState;
+    /**
+     * When true, the user cannot advance past this step (next button is
+     * disabled). Use to gate progression on validation.
+     */
+    disabled?: boolean;
+};
+export type StepState = 'complete' | 'active' | 'upcoming' | 'error';
+export type StepperOrientation = 'horizontal' | 'vertical';
+export type StepperProps = {
+    /** Ordered list of steps. */
+    steps: StepperStep[];
+    /**
+     * Zero-based index of the currently active step. Bindable. @default 0
+     */
+    currentStep?: number;
+    orientation?: StepperOrientation;
+    /** Color accent for the active/complete states. @default 'primary' */
+    color?: VariantColors;
+    /**
+     * Allow clicking completed step markers to jump back. Upcoming steps
+     * are never clickable. @default true
+     */
+    clickableCompleted?: boolean;
+    /** Show the built-in Back/Next navigation below the step list. @default true */
+    showNav?: boolean;
+    /** Back button label. @default 'Back' */
+    backLabel?: string;
+    /** Next button label. @default 'Next' */
+    nextLabel?: string;
+    /** Label for the last step's advance button. @default 'Finish' */
+    finishLabel?: string;
+    /**
+     * Content for the current step. Receives the current index and the
+     * step object so you can render per-step panels.
+     *
+     * ```svelte
+     * {#snippet content(index, step)}
+     *   {#if index === 0}<StepOneForm />{/if}
+     *   {#if index === 1}<StepTwoForm />{/if}
+     * {/snippet}
+     * ```
+     */
+    content?: Snippet<[number, StepperStep]>;
+    /**
+     * Fires when the user advances past the last step. No-op if unset.
+     */
+    onfinish?: () => void;
+    /** Fires whenever `currentStep` changes (from any source). */
+    onchange?: (index: number) => void;
+    /**
+     * Collapse to a compact "Step X of Y · Label" indicator below the
+     * `sm` (640px) breakpoint. Only affects `orientation: 'horizontal'`
+     * — vertical stepping already fits on narrow viewports. @default true
+     */
+    responsive?: boolean;
+    class?: ClassValue;
+    testId?: string;
+};

package/dist/layout/stepper/stepper-types.js

@@ -0,0 +1 @@
+export {};