@ripple-ui/svelte 0.0.0-stage → 0.9.0-next.0

package/dist/manifest.slim.json

@@ -0,0 +1,329 @@
+{
+  "schema": "ripple.manifest.slim/v1",
+  "spec": {
+    "uiField": "ui",
+    "stateField": "state",
+    "version": "1.0",
+    "aliasesNotAllowed": [
+      "root",
+      "tree",
+      "view",
+      "body",
+      "content"
+    ],
+    "description": "A Ripple spec is a JSON object with two top-level fields that matter for rendering: `ui` (the node tree the renderer mounts — REQUIRED) and `state` (the StateManager seed — required when any node uses `bind` or reads `{state.*}`). The renderable tree field is named `ui` exactly — never `root`, `tree`, `view`, `body`, or `content`. Specs that use those aliases will not render. Write `ui` before `state` so the interface can draw while the rest of the spec streams in, and keep the seed `state` small. Leave out any prop whose value equals the default its widget documents. For repeated rows or cards, keep the records as an array in `state` and render them with one `each` node (`\"items\": \"{state.rows}\"`) instead of writing a node per record. Bulk data (more than a few dozen records) should come from the host, through a `sources` binding or an `api` action where the host offers one, not be typed into the spec.",
+    "example": {
+      "version": "1.0",
+      "ui": {
+        "type": "flex",
+        "props": {
+          "direction": "column",
+          "gap": "12px"
+        },
+        "children": [
+          {
+            "type": "input",
+            "bind": "draft",
+            "props": {
+              "placeholder": "Add an item"
+            }
+          }
+        ]
+      },
+      "state": {
+        "draft": "",
+        "items": []
+      }
+    }
+  },
+  "actions": {
+    "set": {
+      "description": "Assign `value` to the state path `target`. The most common action — use it to update any state field.",
+      "shape": {
+        "action": "\"set\"",
+        "target": "string — state path, e.g. \"modalOpen\" or \"user.name\"",
+        "value?": "any — value to assign. Supports {state.x} expressions."
+      },
+      "example": {
+        "action": "set",
+        "target": "modalOpen",
+        "value": false
+      }
+    },
+    "toggle": {
+      "description": "Flip a boolean target, or toggle membership of `value` in an array target.",
+      "shape": {
+        "action": "\"toggle\"",
+        "target": "string — state path. If boolean, value is inverted; if array, `value` is added or removed.",
+        "value?": "any — when target is an array, the membership toggle key."
+      },
+      "example": {
+        "action": "toggle",
+        "target": "expanded"
+      }
+    },
+    "push": {
+      "description": "Append `value` to the array at `target`. Creates the array if undefined.",
+      "shape": {
+        "action": "\"push\"",
+        "target": "string — state path to an array.",
+        "value?": "any — item to append."
+      },
+      "example": {
+        "action": "push",
+        "target": "todos",
+        "value": {
+          "id": 1,
+          "text": "New task",
+          "done": false
+        }
+      }
+    },
+    "remove": {
+      "description": "Remove an item from the array at `target` — by `value` (equality match) or by `index`.",
+      "shape": {
+        "action": "\"remove\"",
+        "target": "string — state path to an array.",
+        "value?": "any — first matching item is removed.",
+        "index?": "number — remove by position instead."
+      },
+      "example": {
+        "action": "remove",
+        "target": "todos",
+        "index": 0
+      }
+    },
+    "open": {
+      "description": "Set the target state path to `true`. Idiomatic shortcut for opening a modal or dialog whose `value` is bound to that path.",
+      "shape": {
+        "action": "\"open\"",
+        "target": "string — state path that controls the modal/dialog open state."
+      },
+      "example": {
+        "action": "open",
+        "target": "confirmDeleteOpen"
+      }
+    },
+    "navigate": {
+      "description": "Host-delegated URL change. The host's `onEvent` callback performs the navigation.",
+      "shape": {
+        "action": "\"navigate\"",
+        "url": "string — destination URL. Supports {state.x} interpolation."
+      },
+      "example": {
+        "action": "navigate",
+        "url": "/projects/{state.selectedId}"
+      }
+    },
+    "toast": {
+      "description": "Show a toast notification. Use after `set` / `api` to give the user feedback.",
+      "shape": {
+        "action": "\"toast\"",
+        "message": "string — toast body. Supports {state.x} interpolation.",
+        "variant?": "\"default\" | \"success\" | \"error\" | \"warning\" | \"info\""
+      },
+      "example": {
+        "action": "toast",
+        "message": "Saved",
+        "variant": "success"
+      }
+    },
+    "emit": {
+      "description": "Emit a custom event up to the host. Use to hand control back to the host pipeline (e.g. \"submit complete, take it from here\").",
+      "shape": {
+        "action": "\"emit\"",
+        "target?": "string — event name.",
+        "value?": "any — event payload."
+      },
+      "example": {
+        "action": "emit",
+        "target": "submitted",
+        "value": "{state.formData}"
+      }
+    },
+    "pin": {
+      "description": "Host-delegated bookmark/pin operation. The host implements the persistence.",
+      "shape": {
+        "action": "\"pin\"",
+        "target?": "string — what is being pinned.",
+        "value?": "any — payload describing the pinned item."
+      },
+      "example": {
+        "action": "pin",
+        "target": "project",
+        "value": "{state.projectId}"
+      }
+    },
+    "unpin": {
+      "description": "Inverse of `pin`. Host-delegated bookmark removal.",
+      "shape": {
+        "action": "\"unpin\"",
+        "target?": "string — what is being unpinned.",
+        "value?": "any"
+      },
+      "example": {
+        "action": "unpin",
+        "target": "project",
+        "value": "{state.projectId}"
+      }
+    }
+  },
+  "widgets": [
+    {
+      "type": "text",
+      "category": "display",
+      "description": "A run of plain text. No markdown.",
+      "props": {
+        "text": {
+          "type": "string",
+          "required": true,
+          "description": "The text."
+        }
+      },
+      "example": {
+        "type": "text",
+        "props": {
+          "text": "Ships in 2 working days."
+        }
+      }
+    },
+    {
+      "type": "heading",
+      "category": "display",
+      "description": "A short title for a block.",
+      "props": {
+        "text": {
+          "type": "string",
+          "required": true,
+          "description": "The title."
+        },
+        "level": {
+          "type": "2 | 3 | 4",
+          "required": false,
+          "description": "Heading level. Default 3."
+        }
+      },
+      "example": {
+        "type": "heading",
+        "props": {
+          "text": "Your options",
+          "level": 3
+        }
+      }
+    },
+    {
+      "type": "badge",
+      "category": "display",
+      "description": "A short status label, such as stock or delivery time.",
+      "props": {
+        "text": {
+          "type": "string",
+          "required": true,
+          "description": "The label."
+        },
+        "variant": {
+          "type": "\"default\" | \"success\" | \"warning\" | \"destructive\"",
+          "required": false,
+          "description": "Default \"default\"."
+        }
+      },
+      "example": {
+        "type": "badge",
+        "props": {
+          "text": "In stock",
+          "variant": "success"
+        }
+      }
+    },
+    {
+      "type": "button",
+      "category": "input",
+      "description": "A button. on_click runs actions: local state, or an emit the host acts on.",
+      "props": {
+        "label": {
+          "type": "string",
+          "required": true,
+          "description": "Button text."
+        },
+        "variant": {
+          "type": "\"default\" | \"secondary\" | \"outline\"",
+          "required": false,
+          "description": "\"default\" for the one main action."
+        },
+        "disabled": {
+          "type": "boolean",
+          "required": false,
+          "description": "Disable the button."
+        }
+      },
+      "events": {
+        "on_click": {
+          "type": "EventAction",
+          "required": false,
+          "description": "Action run on click."
+        }
+      },
+      "example": {
+        "type": "button",
+        "props": {
+          "label": "Show details",
+          "variant": "secondary"
+        },
+        "on_click": {
+          "action": "toggle",
+          "target": "details"
+        }
+      }
+    },
+    {
+      "type": "flex",
+      "category": "layout",
+      "description": "Lays its children out in a row or a column. The only layout atom.",
+      "props": {
+        "direction": {
+          "type": "\"row\" | \"column\"",
+          "required": false,
+          "description": "Default \"column\"."
+        },
+        "gap": {
+          "type": "number",
+          "required": false,
+          "description": "Space between children in px (0-24)."
+        },
+        "align": {
+          "type": "\"start\" | \"center\" | \"end\"",
+          "required": false,
+          "description": "Cross-axis alignment."
+        },
+        "wrap": {
+          "type": "boolean",
+          "required": false,
+          "description": "Wrap a row onto more lines."
+        }
+      },
+      "example": {
+        "type": "flex",
+        "props": {
+          "direction": "row",
+          "gap": 8,
+          "align": "center"
+        },
+        "children": [
+          {
+            "type": "badge",
+            "props": {
+              "text": "In stock",
+              "variant": "success"
+            }
+          },
+          {
+            "type": "text",
+            "props": {
+              "text": "Ships tomorrow"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

package/dist/molecules/ItemCard.svelte

@@ -0,0 +1,213 @@
+<!--
+  ItemCard.svelte — RIPPLE-NATIVE molecule (Wave 1: molecules).
+  Created 2026-06-07.
+  Adapted from ocean-flow's molecules/ItemCard.svelte. Rewired off genesis/
+  shadcn imports onto RIPPLE widgets: display/Image, display/Icon,
+  display/Badge, input/Rating, plus the new PriceTag + SelectionIndicator
+  molecules. Styled with ripple design tokens (ripple-surface / ripple-border /
+  ripple-accent) and Tailwind utilities.
+
+  The workhorse selectable card: image-or-icon + title + subtitle + description
+  + badge + price + rating + selection state, with layout hints. Reused by the
+  browse / select / detail layouts in later waves. Pure presentation — props in,
+  UI out; the only event is an optional `onclick`. No data fetching, no services.
+-->
+<script lang="ts">
+  import { safeUrl } from '@ripple-ui/core';
+  import { cn } from '../utils.js';
+  import Image from '../widgets/display/Image.svelte';
+  import Icon from '../widgets/display/Icon.svelte';
+  import Badge from '../widgets/display/Badge.svelte';
+  import Rating from '../widgets/input/Rating.svelte';
+  import PriceTag from './PriceTag.svelte';
+  import SelectionIndicator from './SelectionIndicator.svelte';
+
+  interface Props {
+    // Required
+    title: string;
+
+    // Optional content
+    subtitle?: string;
+    description?: string;
+    image?: string;
+    /** Lucide icon slug (kebab-case), shown when no image is available. */
+    icon?: string;
+    badge?: string;
+    location?: string;
+
+    // Metadata
+    price?: string | number;
+    originalPrice?: string | number;
+    rating?: number;
+
+    // State
+    selected?: boolean;
+    showSelection?: boolean;
+    /** 'single' → radio dot, 'multiple' → check (passed to SelectionIndicator). */
+    selectionMode?: 'single' | 'multiple';
+
+    // Layout hints
+    showImage?: boolean;
+    showPrice?: boolean;
+    compact?: boolean;
+
+    // Events
+    onclick?: (e?: unknown) => void;
+
+    id?: string;
+    class?: string;
+  }
+
+  let {
+    title,
+    subtitle,
+    description,
+    image,
+    icon,
+    badge,
+    location,
+    price,
+    originalPrice,
+    rating,
+    selected = false,
+    showSelection = false,
+    selectionMode = 'multiple',
+    showImage = true,
+    showPrice = true,
+    compact = false,
+    onclick,
+    id,
+    class: className,
+  }: Props = $props();
+
+  const isValidUrl = $derived(
+    typeof image === 'string' && /^(https?:)?\/\//.test(image),
+  );
+  const hasImage = $derived(showImage && Boolean(image) && isValidUrl);
+  const hasIcon = $derived(!hasImage && Boolean(icon));
+  const hasMetadata = $derived(Boolean(rating) || (showPrice && price != null));
+
+  const isInteractive = $derived(typeof onclick === 'function');
+
+  function onKeydown(e: KeyboardEvent) {
+    if (!isInteractive) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      onclick?.(e);
+    }
+  }
+</script>
+
+<svelte:element
+  this={isInteractive ? 'button' : 'div'}
+  type={isInteractive ? 'button' : undefined}
+  {id}
+  role={isInteractive ? 'button' : undefined}
+  tabindex={isInteractive ? 0 : undefined}
+  aria-pressed={isInteractive ? selected : undefined}
+  onclick={isInteractive ? onclick : undefined}
+  onkeydown={isInteractive ? onKeydown : undefined}
+  class={cn(
+    'group relative flex w-full flex-col overflow-hidden rounded-ripple border bg-ripple-surface text-left text-ripple-surface-foreground transition-all duration-300',
+    isInteractive && 'cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring',
+    selected
+      ? 'border-ripple-accent shadow-md ring-1 ring-inset ring-ripple-accent/30'
+      : 'border-ripple-border/70',
+    isInteractive && !selected && 'hover:-translate-y-0.5 hover:border-ripple-accent/50 hover:shadow-lg',
+    className,
+  )}
+>
+  <!-- Image -->
+  {#if hasImage}
+    <div class="relative aspect-[4/3] w-full overflow-hidden bg-ripple-muted">
+      <Image
+        src={safeUrl(image, { kind: 'resource' })}
+        alt={title}
+        fit="cover"
+        rounded="none"
+        class="h-full w-full transition-transform duration-500 will-change-transform group-hover:scale-105"
+      />
+      {#if badge}
+        <div
+          class="absolute left-2 top-2 rounded-full bg-ripple-surface/90 px-2 py-0.5 text-[10px] font-semibold text-ripple-surface-foreground shadow-sm backdrop-blur-md"
+        >
+          {badge}
+        </div>
+      {/if}
+    </div>
+  {/if}
+
+  <!-- Content -->
+  <div class={cn('flex flex-1 flex-col', compact ? 'p-3' : 'p-4')}>
+    <div class="flex gap-3">
+      <!-- Icon (when no image) -->
+      {#if hasIcon}
+        <div
+          class="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-ripple-accent/10 text-ripple-accent"
+        >
+          <Icon name={icon ?? ''} size={20} />
+        </div>
+      {/if}
+
+      <!-- Text + metadata -->
+      <div class="min-w-0 flex-1">
+        <div class="flex items-start justify-between gap-2">
+          <div class="min-w-0 flex-1">
+            <h3
+              class={cn(
+                'truncate font-semibold leading-tight tracking-tight',
+                compact ? 'text-sm' : 'text-base',
+              )}
+            >
+              {title}
+            </h3>
+            {#if subtitle}
+              <p class="mt-1 truncate text-sm text-muted-foreground">{subtitle}</p>
+            {/if}
+            {#if location}
+              <div
+                class="mt-1.5 flex items-center gap-1 text-xs font-medium text-muted-foreground/80"
+              >
+                <Icon name="map-pin" size={12} class="shrink-0" />
+                <span class="truncate">{location}</span>
+              </div>
+            {/if}
+            {#if badge && !hasImage}
+              <div class="mt-2">
+                <Badge text={badge} variant="secondary" />
+              </div>
+            {/if}
+          </div>
+
+          {#if showSelection}
+            <SelectionIndicator {selected} mode={selectionMode} />
+          {/if}
+        </div>
+
+        {#if description && !compact}
+          <p class="mt-2 line-clamp-2 text-xs text-muted-foreground/80">
+            {description}
+          </p>
+        {/if}
+
+        {#if hasMetadata}
+          <div
+            class="mt-3 flex min-w-0 flex-wrap items-center justify-between gap-2 border-t border-ripple-border/50 pt-3"
+          >
+            {#if rating}
+              <Rating value={rating} size="sm" />
+            {/if}
+            {#if showPrice && price != null}
+              <PriceTag
+                {price}
+                {originalPrice}
+                size={compact ? 'sm' : 'md'}
+                class={cn('min-w-0 max-w-full', rating ? 'ml-auto' : '')}
+              />
+            {/if}
+          </div>
+        {/if}
+      </div>
+    </div>
+  </div>
+</svelte:element>

package/dist/molecules/ItemCard.svelte.d.ts

@@ -0,0 +1,26 @@
+interface Props {
+    title: string;
+    subtitle?: string;
+    description?: string;
+    image?: string;
+    /** Lucide icon slug (kebab-case), shown when no image is available. */
+    icon?: string;
+    badge?: string;
+    location?: string;
+    price?: string | number;
+    originalPrice?: string | number;
+    rating?: number;
+    selected?: boolean;
+    showSelection?: boolean;
+    /** 'single' → radio dot, 'multiple' → check (passed to SelectionIndicator). */
+    selectionMode?: 'single' | 'multiple';
+    showImage?: boolean;
+    showPrice?: boolean;
+    compact?: boolean;
+    onclick?: (e?: unknown) => void;
+    id?: string;
+    class?: string;
+}
+declare const ItemCard: import("svelte").Component<Props, {}, "">;
+type ItemCard = ReturnType<typeof ItemCard>;
+export default ItemCard;

package/dist/molecules/PriceTag.svelte

@@ -0,0 +1,89 @@
+<!--
+  PriceTag.svelte — RIPPLE-NATIVE molecule (Wave 1: molecules).
+  Created 2026-06-07.
+  Adapted from ocean-flow's molecules/PriceTag.svelte, rewired to ripple
+  design tokens (ripple-accent / muted-foreground) and Tailwind utilities.
+
+  Price display with an optional original (strikethrough) price and an
+  optional discount badge derived from the two numeric values. Pure
+  presentation — props in, UI out. No data fetching, no services.
+  2026-09-17 (fix/port-gaps): status-coloured text moved onto the readable
+  text tokens (text-ripple-{error,success,warning,info}-text; red text that
+  read text-destructive now reads text-ripple-error-text, the same hue since
+  --ripple-error aliases --destructive). The raw tones are fill colours and
+  measured 1.7-3.3:1 as text in light mode. Fills and tints are unchanged.
+-->
+<script lang="ts">
+  import { cn } from '../utils.js';
+
+  interface Props {
+    /** Current price. Numbers get a `$` prefix; strings with a leading
+     *  currency symbol ($, €, £) pass through untouched. */
+    price: string | number;
+    /** Optional pre-discount price, rendered struck-through before `price`. */
+    originalPrice?: string | number;
+    /** Show a computed "-N%" discount chip when both prices are numeric. */
+    showDiscount?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    class?: string;
+  }
+
+  let {
+    price,
+    originalPrice,
+    showDiscount = true,
+    size = 'md',
+    class: className = '',
+  }: Props = $props();
+
+  function formatPrice(value: string | number): string {
+    const str = String(value);
+    if (/^[$€£]/.test(str)) return str;
+    return `$${str}`;
+  }
+
+  /** Parse a price-ish value to a number, stripping currency/grouping chars. */
+  function toNumber(value: string | number | undefined): number | null {
+    if (value == null) return null;
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    const cleaned = value.replace(/[^0-9.-]/g, '');
+    const n = Number(cleaned);
+    return Number.isFinite(n) ? n : null;
+  }
+
+  const discountPct = $derived.by(() => {
+    if (!showDiscount || originalPrice == null) return null;
+    const now = toNumber(price);
+    const was = toNumber(originalPrice);
+    if (now == null || was == null || was <= 0 || now >= was) return null;
+    return Math.round((1 - now / was) * 100);
+  });
+
+  const currentSize = $derived(
+    { sm: 'text-sm', md: 'text-base sm:text-lg', lg: 'text-xl sm:text-2xl' }[size],
+  );
+  const originalSize = $derived(
+    { sm: 'text-[11px]', md: 'text-xs sm:text-sm', lg: 'text-sm' }[size],
+  );
+</script>
+
+<div class={cn('flex min-w-0 items-baseline gap-1.5', className)}>
+  {#if originalPrice != null}
+    <span class={cn('shrink-0 text-muted-foreground line-through', originalSize)}>
+      {formatPrice(originalPrice)}
+    </span>
+  {/if}
+  <span
+    class={cn('truncate font-bold text-ripple-accent', currentSize)}
+    title={formatPrice(price)}
+  >
+    {formatPrice(price)}
+  </span>
+  {#if discountPct != null}
+    <span
+      class="shrink-0 rounded-full bg-ripple-success/15 px-1.5 py-0.5 text-[10px] font-semibold leading-none text-ripple-success-text"
+    >
+      -{discountPct}%
+    </span>
+  {/if}
+</div>

package/dist/molecules/PriceTag.svelte.d.ts

@@ -0,0 +1,14 @@
+interface Props {
+    /** Current price. Numbers get a `$` prefix; strings with a leading
+     *  currency symbol ($, €, £) pass through untouched. */
+    price: string | number;
+    /** Optional pre-discount price, rendered struck-through before `price`. */
+    originalPrice?: string | number;
+    /** Show a computed "-N%" discount chip when both prices are numeric. */
+    showDiscount?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    class?: string;
+}
+declare const PriceTag: import("svelte").Component<Props, {}, "">;
+type PriceTag = ReturnType<typeof PriceTag>;
+export default PriceTag;