@makolabs/ripple 2.5.8 → 3.0.0

package/dist/layout/activity-list/ActivityList.svelte

@@ -23,7 +23,7 @@
 		titleClass = '',
 		contentClass = '',
 		itemClass = '',
-		onItemClick,
+		onitemclick,
 		children,
 		customContent
 	}: ActivityListProps = $props();
@@ -116,7 +116,7 @@
 										<div class="flex flex-wrap items-center gap-2">
 											<button
 												class="text-default-900 text-sm font-medium"
-												onclick={() => onItemClick?.(activityItem, index)}
+												onclick={() => onitemclick?.(activityItem, index)}
 											>
 												{activityItem.title}
 											</button>
@@ -126,7 +126,10 @@
 														<Badge color={badge.color} size={Size.SM}>{badge.text}</Badge>
 													{:else if badge.class}
 														<span
-															class="inline-flex rounded-full px-2 py-1 text-xs font-medium {badge.class}"
+															class={cn(
+																'inline-flex rounded-full px-2 py-1 text-xs font-medium',
+																badge.class
+															)}
 														>
 															{badge.text}
 														</span>
@@ -152,7 +155,7 @@
 											size={Size.XS}
 											variant={action.variant ?? 'outline'}
 											color={action.color ?? Color.DEFAULT}
-											onclick={() => action.onClick?.()}
+											onclick={() => action.onclick?.()}
 										>
 											{action.label}
 										</Button>
@@ -164,7 +167,7 @@
 						<div class={itemContent()}>
 							<div class={itemMain()}>
 								<div class={itemHeader()}>
-									<button class={itemTitle()} onclick={() => onItemClick?.(activityItem, index)}>
+									<button class={itemTitle()} onclick={() => onitemclick?.(activityItem, index)}>
 										{activityItem.title}
 									</button>
 									{#if activityItem.badges}
@@ -173,7 +176,10 @@
 												<Badge color={badge.color} size={Size.SM}>{badge.text}</Badge>
 											{:else if badge.class}
 												<span
-													class="inline-flex rounded-full px-2 py-1 text-xs font-medium {badge.class}"
+													class={cn(
+														'inline-flex rounded-full px-2 py-1 text-xs font-medium',
+														badge.class
+													)}
 												>
 													{badge.text}
 												</span>
@@ -203,7 +209,7 @@
 											size={Size.XS}
 											variant={action.variant ?? 'outline'}
 											color={action.color ?? Color.DEFAULT}
-											onclick={() => action.onClick?.()}
+											onclick={() => action.onclick?.()}
 										>
 											{action.label}
 										</Button>

package/dist/layout/activity-list/activity-list-types.d.ts

@@ -1,28 +1,30 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { Snippet, Component } from 'svelte';
 import type { VariantColors } from '../../index.js';
+/** A small label attached to an `ActivityItem` (status, type, priority). */
 export type ActivityItemBadge = {
     text: string;
     /**
      * Ripple color for the badge. Renders as a `<Badge color={color}>`
-     * in ripple's design system. Preferred over `class` for new code.
+     * in ripple's design system. Preferred over `class` for arbitrary styling.
      */
     color?: VariantColors;
     /**
-     * Legacy Tailwind class string for the badge (e.g. 'bg-green-100 text-green-800').
-     * Kept for backward compatibility with pre-v2.1 callers. If both `color`
-     * and `class` are provided, `color` wins.
+     * Tailwind class string for ad-hoc badge styling (e.g. 'bg-green-100
+     * text-green-800'). If both `color` and `class` are provided, `color` wins.
      */
-    class?: string;
+    class?: ClassValue;
 };
+/** Button-style action attached to an `ActivityItem` (e.g. "View details", "Mark done"). */
 export type ActivityItemAction = {
     label: string;
-    onClick?: () => void;
+    onclick?: () => void;
     /** Optional ripple button color variant. @default 'default' */
     color?: VariantColors;
     /** Optional ripple button variant. @default 'outline' */
     variant?: 'solid' | 'outline' | 'ghost' | 'link';
 };
+/** Single entry in an `<ActivityList>`. Many fields are optional — use what you need. */
 export type ActivityItem = {
     title: string;
     subtitle?: string;
@@ -75,7 +77,44 @@ export type ActivityItem = {
      */
     custom?: boolean;
 };
+/** Density variants specific to ActivityList. */
 export type ActivityListSize = 'sm' | 'md';
+/**
+ * Props for `<ActivityList>` — a feed of recent events / actions (audit
+ * trails, user activity, timeline views). Each `ActivityItem` has a
+ * title/subtitle, optional icon, badges, actions, and can be rendered
+ * as a connected timeline.
+ *
+ * For a single metric card use `<MetricCard>`; for tabular data with
+ * sorting/selection use `<Table>`.
+ *
+ * @example
+ * ```svelte
+ * <ActivityList
+ *   title="Recent activity"
+ *   items={[
+ *     {
+ *       title: 'Order #1284 shipped',
+ *       subtitle: '3 packages · Tracking ACN-2931',
+ *       icon: ShippedIcon,
+ *       iconColor: 'success',
+ *       timestamp: '2m ago',
+ *       badges: [{ text: 'Shipped', color: 'success' }]
+ *     }
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Timeline with a per-row custom cell (chart/progress) -->
+ * <ActivityList items={richItems} timeline>
+ *   {#snippet customContent(item, i)}
+ *     <Chart data={item.chart} config={miniChartConfig} />
+ *   {/snippet}
+ * </ActivityList>
+ * ```
+ */
 export type ActivityListProps = {
     title?: string;
     items?: ActivityItem[];
@@ -98,7 +137,7 @@ export type ActivityListProps = {
     titleClass?: ClassValue;
     contentClass?: ClassValue;
     itemClass?: ClassValue;
-    onItemClick?: (item: ActivityItem, index: number) => void;
+    onitemclick?: (item: ActivityItem, index: number) => void;
     children?: Snippet;
     /**
      * Optional snippet used to render the content area of any item

package/dist/layout/card/Card.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
 	import { cn } from '../../helper/cls.js';
 	import { buildTestId } from '../../helper/testid.js';
-	import { warnDeprecatedProps } from '../../helper/deprecation.js';
 	import { card } from './card.js';
+	import Skeleton from '../../elements/skeleton/Skeleton.svelte';
 	import type { CardProps } from '../../index.js';
 	import { Color } from '../../variants.js';
 
@@ -12,22 +12,12 @@
 		title,
 		color = Color.DEFAULT,
 		class: className = '',
-		titleclass,
-		titleClass = titleclass ?? '',
-		bodyclass,
-		bodyClass = bodyclass ?? '',
+		titleClass = '',
+		bodyClass = '',
+		loading = false,
 		testId
 	}: CardProps = $props();
 
-	warnDeprecatedProps(
-		'Card',
-		{ titleclass, bodyclass },
-		{
-			titleclass: 'titleClass',
-			bodyclass: 'bodyClass'
-		}
-	);
-
 	const { base, title: titleSlot, body: bodySlot } = $derived(card({ color }));
 
 	const baseClass = $derived(cn(base(), className));
@@ -36,7 +26,14 @@
 </script>
 
 <div class={baseClass} data-testid={buildTestId('card', undefined, testId)}>
-	{#if custom}
+	{#if loading}
+		<Skeleton class="mb-3 h-5 w-1/2" />
+		<div class="space-y-2">
+			<Skeleton class="h-3 w-full" />
+			<Skeleton class="h-3 w-5/6" />
+			<Skeleton class="h-3 w-3/4" />
+		</div>
+	{:else if custom}
 		{@render custom()}
 	{:else}
 		{#if title}

package/dist/layout/card/MetricCard.svelte

@@ -3,6 +3,7 @@
 	import { metricCard } from './metric-card.js';
 	import type { MetricCardProps } from '../../index.js';
 	import Progress from '../../elements/progress/Progress.svelte';
+	import Skeleton from '../../elements/skeleton/Skeleton.svelte';
 	import { Size, Color } from '../../variants.js';
 
 	let {
@@ -14,7 +15,8 @@
 		class: className = '',
 		onclick,
 		action,
-		actionHover
+		actionHover,
+		loading = false
 	}: MetricCardProps = $props();
 
 	const interactive = $derived(!!onclick);
@@ -72,40 +74,56 @@
 		{/if}
 	{/if}
 
-	{#if title}
-		<div class={titleSlot()}>{title}</div>
-	{/if}
+	{#if loading}
+		<Skeleton class="h-3 w-1/2" />
+		<Skeleton class="mt-2 h-9 w-2/3" />
+		<div class="mt-3 space-y-2">
+			<div class="flex justify-between">
+				<Skeleton class="h-3 w-20" /><Skeleton class="h-3 w-12" />
+			</div>
+			<div class="flex justify-between">
+				<Skeleton class="h-3 w-24" /><Skeleton class="h-3 w-10" />
+			</div>
+			<div class="flex justify-between">
+				<Skeleton class="h-3 w-16" /><Skeleton class="h-3 w-14" />
+			</div>
+		</div>
+	{:else}
+		{#if title}
+			<div class={titleSlot()}>{title}</div>
+		{/if}
 
-	{#if value !== undefined}
-		<div class={valueSlot()}>{value}</div>
-	{/if}
+		{#if value !== undefined}
+			<div class={valueSlot()}>{value}</div>
+		{/if}
 
-	{#if details.length > 0}
-		<div class={detailSlot()}>
-			{#each details as detail, index (detail.label + index)}
-				<div class="flex justify-between text-xs">
-					<span class="text-default-500">{detail.label}</span>
-					<span class="font-medium {detail.color || 'text-default-900'}">{detail.value}</span>
-				</div>
-			{/each}
-		</div>
-	{/if}
+		{#if details.length > 0}
+			<div class={detailSlot()}>
+				{#each details as detail, index (detail.label + index)}
+					<div class="flex justify-between text-xs">
+						<span class="text-default-500">{detail.label}</span>
+						<span class="font-medium {detail.color || 'text-default-900'}">{detail.value}</span>
+					</div>
+				{/each}
+			</div>
+		{/if}
 
-	{#if segments}
-		<div class={cn(progressSlot(), 'pt-2')}>
-			<Progress
-				value={0}
-				{segments}
-				size={Size.SM}
-				showLabels={false}
-				showValues={false}
-				showLabel={false}
-			/>
-		</div>
-	{:else if percent !== undefined}
-		<div class={cn(progressSlot(), 'pt-2')}>
-			<Progress value={percent} size={Size.SM} color={Color.SUCCESS} showLabel={false} />
-		</div>
+		{#if segments}
+			<div class={cn(progressSlot(), 'pt-2')}>
+				<Progress
+					value={0}
+					{segments}
+					size={Size.SM}
+					showLabels={false}
+					showValues={false}
+					showLabel={false}
+				/>
+			</div>
+		{:else if percent !== undefined}
+			<div class={cn(progressSlot(), 'pt-2')}>
+				<Progress value={percent} size={Size.SM} color={Color.SUCCESS} showLabel={false} />
+			</div>
+		{/if}
 	{/if}
 {/snippet}
 

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

@@ -3,40 +3,145 @@ import type { Snippet } from 'svelte';
 import type { Component } from 'svelte';
 import type { VariantColors } from '../../index.js';
 import type { ProgressSegment } from '../../elements/progress/progress-types.js';
+/**
+ * Props for `<Card>` — a generic bordered container with optional
+ * title and color tint. Use for grouping related content, often with
+ * a skeleton placeholder while loading.
+ *
+ * For number-focused cards (KPIs, metrics), use `<MetricCard>` instead.
+ * For ranked lists (leaderboards), use `<RankedCard>`.
+ *
+ * @example
+ * ```svelte
+ * <Card title="Recent activity" color="info">
+ *   <ul>
+ *     {#each items as item}
+ *       <li>{item.title}</li>
+ *     {/each}
+ *   </ul>
+ * </Card>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Skeleton placeholder while fetching -->
+ * <Card title="Portfolio" {loading}>
+ *   {#if data}<Chart {data} {config} />{/if}
+ * </Card>
+ * ```
+ */
 export type CardProps = {
+    /** Background tint. @default 'default' */
     color?: VariantColors;
+    /** Heading shown at the top. */
     title?: string;
     class?: ClassValue;
-    /** @deprecated Use titleClass instead */
-    titleclass?: ClassValue;
+    /** Classes for the title element only. */
     titleClass?: ClassValue;
-    /** @deprecated Use bodyClass instead */
-    bodyclass?: ClassValue;
+    /** Classes for the body container only. */
     bodyClass?: ClassValue;
+    /** Default body content. */
     children?: Snippet;
+    /**
+     * Override the entire card body with arbitrary markup. When provided,
+     * `children` is ignored. Use for custom card shells that still want
+     * the Card's border/shadow but not the title+body scaffolding.
+     */
     custom?: Snippet;
+    /**
+     * Show a skeleton placeholder (title + body) instead of the children
+     * while data is loading. @default false
+     */
+    loading?: boolean;
     testId?: string;
 };
+/**
+ * Props for `<Alert>` — a prominent inline banner for success / warning /
+ * error / info messages. Use at the top of a page or above a form. For
+ * transient notifications prefer `toast()`; for system-level callouts
+ * (page offline, session expiring) use Alert.
+ *
+ * @example
+ * ```svelte
+ * <Alert title="Saved" message="Your changes have been saved." color="success" />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Dismissable with a custom footer action -->
+ * <Alert color="warning" message="Your trial ends in 3 days." onclose={() => {}}>
+ *   {#snippet footer()}
+ *     <Button size="sm">Upgrade now</Button>
+ *   {/snippet}
+ * </Alert>
+ * ```
+ */
 export type AlertProps = {
+    /** Heading shown above the message in bold. */
     title?: string;
+    /** Primary message text. */
     message: string;
+    /** Semantic color — drives icon, border, and background tint. @default 'info' */
     color?: VariantColors;
     class?: ClassValue;
+    /** When provided, renders a × dismiss button. */
     onclose?: () => void;
+    /** Additional content below the message (e.g. action buttons). */
     footer?: Snippet;
+    /** Override the default color-appropriate icon. */
     icon?: Component;
     testId?: string;
 };
+/**
+ * A single metric shown in `<MetricCard>`'s detail list (e.g.
+ * breaking a total into sub-metrics).
+ */
 export type MetricDetail = {
     label: string;
     value: string | number;
+    /** Visual accent for the value. */
     color?: VariantColors;
 };
+/**
+ * Props for `<MetricCard>` — a KPI-focused card that shows a single
+ * primary value, optional percentage/progress bar, and optional detail
+ * breakdowns. Becomes clickable when `onclick` is provided.
+ *
+ * @example
+ * ```svelte
+ * <MetricCard title="Revenue (MTD)" value="$142K" percent={68} />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Clickable KPI with a hover action -->
+ * <MetricCard
+ *   title="Active users"
+ *   value={users.toLocaleString()}
+ *   onclick={() => goto('/users')}
+ *   details={[
+ *     { label: 'New', value: 42, color: 'success' },
+ *     { label: 'Churned', value: 7, color: 'danger' }
+ *   ]}
+ * />
+ * ```
+ */
 export type MetricCardProps = {
+    /** Small label above the headline value. */
     title: string;
+    /** Headline value — the big number. */
     value: string | number;
+    /** Optional breakdown rendered as a small list below the value. */
     details?: MetricDetail[];
+    /**
+     * Progress bar percentage (0-100). When set, renders a single-segment
+     * progress bar below the value.
+     */
     percent?: number;
+    /**
+     * Multi-segment progress (e.g. "50% healthy / 30% warning / 20% danger").
+     * Takes precedence over `percent` when both are set.
+     */
     segments?: ProgressSegment[];
     class?: ClassValue;
     /**
@@ -58,5 +163,10 @@ export type MetricCardProps = {
      * is set.
      */
     actionHover?: Snippet;
+    /**
+     * Show a skeleton placeholder instead of the title/value/details while
+     * data is loading. @default false
+     */
+    loading?: boolean;
     testId?: string;
 };

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

@@ -1,19 +1,67 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { Snippet } from 'svelte';
 import type { Component } from 'svelte';
+/**
+ * Single navbar link — may have nested children for dropdown menus.
+ * Active state is typically driven by your router; this type carries
+ * an `active` flag for consumers to set explicitly when needed.
+ */
 export type NavbarLinkItem = {
     label: string;
+    /** Target URL. */
     href: string;
     icon?: Component;
+    /** Render as the current route (active styling). */
     active?: boolean;
+    /** Nested links — when set, the item renders a dropdown menu. */
     children?: NavbarLinkItem[];
 };
+/**
+ * Props for `<Navbar>` — a horizontal top-of-page navigation bar.
+ * For a side-rail navigation, use `<Sidebar>` instead. Many apps use
+ * both (Navbar for global, Sidebar for within-app).
+ *
+ * @example
+ * ```svelte
+ * <Navbar
+ *   logo="/logo.svg"
+ *   links={[
+ *     { label: 'Dashboard', href: '/', active: true },
+ *     { label: 'Reports', href: '/reports' },
+ *     {
+ *       label: 'Settings',
+ *       href: '/settings',
+ *       children: [
+ *         { label: 'Profile', href: '/settings/profile' },
+ *         { label: 'Billing', href: '/settings/billing' }
+ *       ]
+ *     }
+ *   ]}
+ * >
+ *   {#snippet actions()}
+ *     <Button variant="ghost">Sign out</Button>
+ *   {/snippet}
+ * </Navbar>
+ * ```
+ */
 export type NavbarProps = {
+    /**
+     * Logo to render on the left. Pass a string path for an `<img>` or a
+     * Component for inline SVG. Prefer the `brand` snippet for fully
+     * custom branding (logo + wordmark + tagline, etc.).
+     */
     logo?: string | Component;
+    /** Main navigation links. */
     links?: NavbarLinkItem[];
     class?: ClassValue;
+    /**
+     * Custom brand content (takes precedence over `logo`). Render whatever
+     * markup you want for the brand area.
+     */
     brand?: Snippet;
+    /** Fallback slot — rendered between the links and `actions`. */
     children?: Snippet;
+    /** Right-aligned action area — profile menu, notifications, sign-out, etc. */
     actions?: Snippet;
     testId?: string;
 };

package/dist/layout/navbar/navbar.d.ts

@@ -38,7 +38,7 @@ export declare const navbar: import("tailwind-variants").TVReturnType<{
             link: string;
             mobileLink: string;
         };
-        base: {
+        md: {
             container: string;
             link: string;
             mobileLink: string;
@@ -100,7 +100,7 @@ export declare const navbar: import("tailwind-variants").TVReturnType<{
             link: string;
             mobileLink: string;
         };
-        base: {
+        md: {
             container: string;
             link: string;
             mobileLink: string;
@@ -162,7 +162,7 @@ export declare const navbar: import("tailwind-variants").TVReturnType<{
             link: string;
             mobileLink: string;
         };
-        base: {
+        md: {
             container: string;
             link: string;
             mobileLink: string;

package/dist/layout/navbar/navbar.js

@@ -50,7 +50,7 @@ export const navbar = tv({
                 link: 'text-xs',
                 mobileLink: 'text-xs'
             },
-            [Size.BASE]: {
+            [Size.MD]: {
                 container: 'h-16',
                 link: 'text-sm',
                 mobileLink: 'text-sm'
@@ -93,7 +93,7 @@ export const navbar = tv({
     ],
     defaultVariants: {
         color: Color.DEFAULT,
-        size: Size.BASE,
+        size: Size.MD,
         active: false
     }
 });