@m3000/market 0.0.1

package/src/styles/theme/color.css

@@ -0,0 +1,185 @@
+@theme {
+  /* ============================================================
+     PRIMITIVE SCALE - based on Radix UI grey scale
+     Light mode values (used directly) / Dark mode has separate scale
+     ============================================================ */
+
+  /* Light mode primitives (Radix gray 1-12) */
+  --color-grey-1: #fcfcfc;
+  --color-grey-2: #f9f9f9;
+  --color-grey-3: #f0f0f0;
+  --color-grey-4: #e8e8e8;
+  --color-grey-5: #e0e0e0;
+  --color-grey-6: #d9d9d9;
+  --color-grey-7: #cecece;
+  --color-grey-8: #bbbbbb;
+  --color-grey-9: #8d8d8d;
+  --color-grey-10: #838383;
+  --color-grey-11: #646464;
+  --color-grey-12: #202020;
+
+  --color-white: #ffffff;
+  --color-black: #111111;
+  --color-current: currentColor;
+  --color-transparent: transparent;
+
+  /* ============================================================
+     SEMANTIC TOKENS (shadcn naming) - light mode defaults
+     Using Radix scale semantics:
+     1-2: backgrounds, 3-5: component bg, 6-8: borders, 11-12: text
+     ============================================================ */
+
+  /* Page backgrounds */
+  --color-background: var(--color-white);
+  --color-foreground: var(--color-grey-12);
+
+  /* Muted surfaces (cards, secondary backgrounds) */
+  --color-muted: var(--color-grey-2);
+  --color-muted-foreground: var(--color-grey-11);
+
+  /* Card surfaces */
+  --color-card: var(--color-white);
+  --color-card-foreground: var(--color-grey-12);
+
+  /* Popover surfaces */
+  --color-popover: var(--color-white);
+  --color-popover-foreground: var(--color-grey-12);
+
+  /* Primary actions (solid buttons) */
+  --color-primary: var(--color-grey-12);
+  --color-primary-hover: var(--color-grey-11);
+  --color-primary-foreground: var(--color-white);
+
+  /* Secondary actions */
+  --color-secondary: var(--color-grey-3);
+  --color-secondary-hover: var(--color-grey-4);
+  --color-secondary-foreground: var(--color-grey-12);
+
+  /* Accent (interactive element backgrounds) */
+  --color-accent: var(--color-grey-3);
+  --color-accent-hover: var(--color-grey-4);
+  --color-accent-active: var(--color-grey-5);
+  --color-accent-foreground: var(--color-grey-12);
+
+  /* Borders - using Radix steps 6-7 for subtle borders */
+  --color-border: var(--color-grey-6);
+  --color-input: var(--color-grey-7);
+  --color-ring: var(--color-grey-12);
+
+  /* Disabled states */
+  --color-disabled: var(--color-grey-3);
+  --color-disabled-foreground: var(--color-grey-9);
+
+  /* Destructive/Error */
+  --color-destructive: #e5484d;
+  --color-destructive-hover: #dc3d43;
+  --color-destructive-foreground: var(--color-white);
+  --color-destructive-muted: #fff8f8;
+  --color-destructive-muted-foreground: #cd2b31;
+
+  /* Success */
+  --color-success: #30a46c;
+  --color-success-hover: #2b9a64;
+  --color-success-foreground: var(--color-white);
+  --color-success-muted: #e9f9ee;
+  --color-success-muted-foreground: #18794e;
+
+  /* Warning/Alert */
+  --color-warning: #f5d90a;
+  --color-warning-hover: #e5c800;
+  --color-warning-foreground: var(--color-grey-12);
+  --color-warning-muted: #fefce9;
+  --color-warning-muted-foreground: #946800;
+
+  /* Separator (subtle dividers) */
+  --color-separator: var(--color-grey-3);
+}
+
+/* ============================================================
+   DARK MODE - using Radix dark grey scale for proper layering
+   ============================================================ */
+@layer base {
+  @variant dark {
+    /* Dark mode primitives (Radix gray-dark 1-12) 
+       These override the light primitives contextually */
+    --color-grey-1: #111111;
+    --color-grey-2: #191919;
+    --color-grey-3: #222222;
+    --color-grey-4: #2a2a2a;
+    --color-grey-5: #313131;
+    --color-grey-6: #3a3a3a;
+    --color-grey-7: #484848;
+    --color-grey-8: #606060;
+    --color-grey-9: #6e6e6e;
+    --color-grey-10: #7b7b7b;
+    --color-grey-11: #b4b4b4;
+    --color-grey-12: #eeeeee;
+
+    --color-black: #111111;
+
+    /* Page backgrounds */
+    --color-background: var(--color-grey-1);
+    --color-foreground: var(--color-grey-12);
+
+    /* Muted surfaces - step 2 for subtle elevation */
+    --color-muted: var(--color-grey-2);
+    --color-muted-foreground: var(--color-grey-11);
+
+    /* Card surfaces */
+    --color-card: var(--color-grey-2);
+    --color-card-foreground: var(--color-grey-12);
+
+    /* Popover surfaces */
+    --color-popover: var(--color-grey-2);
+    --color-popover-foreground: var(--color-grey-12);
+
+    /* Primary actions */
+    --color-primary: var(--color-grey-12);
+    --color-primary-hover: var(--color-white);
+    --color-primary-foreground: var(--color-grey-1);
+
+    /* Secondary actions - steps 3-4 */
+    --color-secondary: var(--color-grey-3);
+    --color-secondary-hover: var(--color-grey-4);
+    --color-secondary-foreground: var(--color-grey-12);
+
+    /* Accent - steps 3-5 */
+    --color-accent: var(--color-grey-3);
+    --color-accent-hover: var(--color-grey-4);
+    --color-accent-active: var(--color-grey-5);
+    --color-accent-foreground: var(--color-grey-12);
+
+    /* Borders - step 6 for subtle, step 7 for interactive */
+    --color-border: var(--color-grey-6);
+    --color-input: var(--color-grey-7);
+    --color-ring: var(--color-grey-12);
+
+    /* Disabled states */
+    --color-disabled: var(--color-grey-3);
+    --color-disabled-foreground: var(--color-grey-9);
+
+    /* Destructive/Error */
+    --color-destructive: #e5484d;
+    --color-destructive-hover: #f16a6e;
+    --color-destructive-foreground: var(--color-white);
+    --color-destructive-muted: #291415;
+    --color-destructive-muted-foreground: #ff6369;
+
+    /* Success */
+    --color-success: #30a46c;
+    --color-success-hover: #3cb77a;
+    --color-success-foreground: var(--color-white);
+    --color-success-muted: #0d2117;
+    --color-success-muted-foreground: #4cc38a;
+
+    /* Warning/Alert */
+    --color-warning: #f5d90a;
+    --color-warning-hover: #ffe629;
+    --color-warning-foreground: var(--color-grey-12);
+    --color-warning-muted: #1c1500;
+    --color-warning-muted-foreground: #f0c000;
+
+    /* Separator */
+    --color-separator: var(--color-grey-3);
+  }
+}

package/src/styles/theme/index.css

@@ -0,0 +1,3 @@
+@import "./color.css";
+@import "./typography.css";
+@import "./animation.css";

package/src/styles/theme/typography.css

@@ -0,0 +1,3 @@
+@theme inline {
+  --font-sans: var(--font-zeit), ui-sans-serif, system-ui, sans-serif;
+}

package/src/styles/utility.css

@@ -0,0 +1,8 @@
+/* Dark theme via class */
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* Helpers for data attributes (Base UI) */
+@custom-variant data-active (&[data-state~="active"]);
+@custom-variant data-open (&[data-state~="open"]);
+@custom-variant data-close (&[data-state~="close"]);
+@custom-variant data-disabled (&[data-state~="disabled"]);

package/src/types/index.ts

@@ -0,0 +1,149 @@
+// ─── Auction Data Types ─────────────────────────────────────────────────────
+
+/**
+ * Tick configuration for the auction's price grid.
+ * Prices below the threshold use smallTickSize; prices above use largeTickSize.
+ */
+export interface AuctionTickConfig {
+  threshold: bigint;
+  smallTickSize: bigint;
+  largeTickSize: bigint;
+}
+
+/**
+ * Core auction data. All prices are in bigint.
+ * This type is fully generic -- no blockchain or framework coupling.
+ */
+export interface AuctionData {
+  /** Unique identifier for the auction */
+  id: string;
+  /** Minimum accepted bid price */
+  reservePrice: bigint;
+  /** Final clearing price after settlement, if finalized */
+  clearingPrice?: bigint;
+  /** When the auction opens for bidding (null = already open) */
+  opensAt: Date | null;
+  /** When the auction closes (null = no end time set) */
+  endsAt: Date | null;
+  /** Maximum number of winning bidders / editions */
+  maxTotalItems: number;
+  /** Tick configuration for bid price stepping */
+  tickConfig?: AuctionTickConfig;
+}
+
+// ─── Bid Types ──────────────────────────────────────────────────────────────
+
+/**
+ * A bidder's public profile. Consumers map their own user type into this.
+ */
+export interface AuctionBidder {
+  /** Unique user identifier (e.g. wallet address) */
+  id: string;
+  /** Display name */
+  name?: string;
+  /** Avatar image URL */
+  avatarUrl?: string;
+}
+
+/**
+ * A single bid in the auction leaderboard (public view).
+ * All prices are in the auction's native unit as bigint.
+ */
+export interface AuctionBid {
+  /** Unique bid identifier */
+  id: string;
+  /** Bid price */
+  price: bigint;
+  /** When the bid was placed */
+  createdAt: Date;
+  /** The bidder */
+  bidder: AuctionBidder;
+  /** Link to the bid transaction on a block explorer */
+  explorerUrl?: string;
+}
+
+/** Bid status for user's own bids */
+export type AuctionBidStatus = "active" | "refunded" | "claimed";
+
+/**
+ * Extended bid data for the current user's bids.
+ * Includes status and claim information.
+ */
+export interface AuctionUserBid extends AuctionBid {
+  /** On-chain global bid ID (used for top-up) */
+  globalBidId: bigint;
+  /** Current bid status */
+  status: AuctionBidStatus;
+  /** Whether this bid is currently in the winning range */
+  isWinning: boolean;
+  /** When the item was claimed (for winning bids) */
+  claimedAt?: Date;
+  /** Refund transaction explorer URL */
+  refundExplorerUrl?: string;
+}
+
+// ─── Operation Status ───────────────────────────────────────────────────────
+
+/** Status of an async operation (bid placement, top-up, claim) */
+export type OperationStatus =
+  | "idle"
+  | "pending"
+  | "confirming"
+  | "indexing"
+  | "success"
+  | "error";
+
+/** Tracks the state of an in-flight operation */
+export interface OperationState {
+  status: OperationStatus;
+  error?: string;
+}
+
+// ─── Callbacks ──────────────────────────────────────────────────────────────
+
+/**
+ * Callbacks that consumers must provide to wire up blockchain/API operations.
+ * All return a boolean indicating success/failure.
+ */
+export interface AuctionCallbacks {
+  /** Place a new bid. Called with price and quantity. */
+  onPlaceBid: (price: bigint, quantity: bigint) => Promise<boolean>;
+  /** Top up an existing bid to a new price. */
+  onTopUpBid: (
+    bidId: bigint,
+    newPrice: bigint,
+    additionalValue: bigint,
+  ) => Promise<boolean>;
+  /** Claim an item for a winning bid. Optional. */
+  onClaimEdition?: (bidId: string) => Promise<boolean>;
+}
+
+// ─── Formatters ─────────────────────────────────────────────────────────────
+
+/**
+ * Formatting functions consumers can provide to customize display.
+ * All are optional -- sensible defaults are used when not provided.
+ */
+export interface AuctionFormatters {
+  /** Format a price value for display. Default: divide by 10^decimals */
+  formatPrice?: (priceValue: bigint) => string;
+  /** Format a date for display. Default: relative time (e.g. "5m ago") */
+  formatTime?: (date: Date) => string;
+  /** Currency symbol to display alongside prices. Default: "USD" */
+  currencySymbol?: string;
+  /** Number of decimal places used when editing bigint-backed prices. */
+  inputDecimals?: number;
+}
+
+// ─── Internal Rankable Bid ──────────────────────────────────────────────────
+
+/**
+ * Lightweight bid representation used internally for rank calculations.
+ * Consumers don't need to use this directly -- it's derived from AuctionBid.
+ */
+export interface RankableBid {
+  id: string;
+  price: string;
+  created_at: string;
+  bidder?: AuctionBidder;
+}

package/src/utils/format.ts

@@ -0,0 +1,130 @@
+/**
+ * Default price formatter: converts wei (bigint) to a human-readable ETH string.
+ * Uses native bigint arithmetic -- no external dependencies.
+ */
+export function formatWeiToEth(wei: bigint, decimals: number = 18): string {
+  const isNegative = wei < 0n;
+  const abs = isNegative ? -wei : wei;
+  const divisor = 10n ** BigInt(decimals);
+  const whole = abs / divisor;
+  const remainder = abs % divisor;
+
+  if (remainder === 0n) {
+    return `${isNegative ? "-" : ""}${whole.toString()}`;
+  }
+
+  // Pad remainder to full decimal length and strip trailing zeros
+  const remainderStr = remainder.toString().padStart(decimals, "0");
+  const trimmed = remainderStr.replace(/0+$/, "");
+
+  return `${isNegative ? "-" : ""}${whole.toString()}.${trimmed}`;
+}
+
+/**
+ * Parses an ETH string (e.g. "0.01") to wei (bigint).
+ * Inverse of formatWeiToEth.
+ */
+export function parseEthToWei(eth: string, decimals: number = 18): bigint {
+  const [wholePart = "0", fracPart = ""] = eth.split(".");
+  const paddedFrac = fracPart.padEnd(decimals, "0").slice(0, decimals);
+  return BigInt(wholePart) * 10n ** BigInt(decimals) + BigInt(paddedFrac);
+}
+
+/**
+ * Formats a date as a short relative time string.
+ * Examples: "now", "5m", "2h", "3d", "2w"
+ */
+export function formatShortRelative(date: Date): string {
+  const now = Date.now();
+  const diff = now - date.getTime();
+  const secs = Math.floor(diff / 1000);
+
+  if (secs < 60) return "now";
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d`;
+  return `${Math.min(Math.floor(days / 7), 99)}w`;
+}
+
+/**
+ * Formats a date as a full timestamp string.
+ * Example: "09 Mar 2026 at 14:30"
+ */
+export function formatFullTimestamp(date: Date): string {
+  const day = date.getDate().toString().padStart(2, "0");
+  const months = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+  ];
+  const month = months[date.getMonth()];
+  const year = date.getFullYear();
+  const hours = date.getHours().toString().padStart(2, "0");
+  const minutes = date.getMinutes().toString().padStart(2, "0");
+  return `${day} ${month} ${year} at ${hours}:${minutes}`;
+}
+
+/**
+ * Formats a date as a short date string.
+ * Example: "09 Mar 2026"
+ */
+export function formatShortDate(date: Date): string {
+  const day = date.getDate().toString().padStart(2, "0");
+  const months = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+  ];
+  const month = months[date.getMonth()];
+  const year = date.getFullYear();
+  return `${day} ${month} ${year}`;
+}
+
+/**
+ * Formats a date as a full date-time string for display.
+ * Example: "09 Mar 2026 at 14:30"
+ */
+export function formatDateTime(date: Date): string {
+  return formatFullTimestamp(date);
+}
+
+/**
+ * Formats a countdown duration in ms to "DDd:HHh:MMm:SSs" format.
+ * If elapsed is negative (time has passed), counts up (shows elapsed time).
+ */
+export function formatCountdownString(remainingMs: number): string {
+  const absMs = Math.abs(remainingMs);
+  const totalSeconds = Math.floor(absMs / 1000);
+  const days = Math.floor(totalSeconds / 86400);
+  const hours = Math.floor((totalSeconds % 86400) / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  const dd = days.toString().padStart(2, "0");
+  const hh = hours.toString().padStart(2, "0");
+  const mm = minutes.toString().padStart(2, "0");
+  const ss = seconds.toString().padStart(2, "0");
+
+  return `${dd}d:${hh}h:${mm}m:${ss}s`;
+}

package/src/utils/index.ts

@@ -0,0 +1,16 @@
+export {
+  formatCountdownString,
+  formatDateTime,
+  formatFullTimestamp,
+  formatShortDate,
+  formatShortRelative,
+  formatWeiToEth,
+  parseEthToWei,
+} from "./format";
+export type { ProjectedRankResult, SuggestedBidsInput } from "./rank-utils";
+export { getProjectedRankForPrice, getSuggestedBidPrices } from "./rank-utils";
+export {
+  getActiveTickSize,
+  isValidTickPrice,
+  roundDownToValidBid,
+} from "./tick-validation";

package/src/utils/rank-utils.ts

@@ -0,0 +1,131 @@
+import type { AuctionTickConfig, RankableBid } from "@/types";
+import { getActiveTickSize, roundDownToValidBid } from "./tick-validation";
+
+export interface ProjectedRankResult {
+  rank: number | null;
+  isWinning: boolean;
+}
+
+/**
+ * Projects where a bid at a given price would land in the current rankings.
+ * Returns the 1-based rank and whether it would be in the winning range.
+ */
+export function getProjectedRankForPrice(
+  priceValue: bigint,
+  mergedForRank: RankableBid[],
+  maxTotalItems: number,
+): ProjectedRankResult {
+  if (priceValue <= 0n) return { rank: null, isWinning: false };
+  const synthetic: RankableBid = {
+    id: "__synthetic__",
+    price: priceValue.toString(),
+    created_at: new Date().toISOString(),
+  };
+
+  const sorted = [...mergedForRank, synthetic].sort((a, b) => {
+    const priceA = BigInt(a.price);
+    const priceB = BigInt(b.price);
+    if (priceA !== priceB) return priceB > priceA ? 1 : -1;
+
+    // Tie-breaker: synthetic bid sorts below same-priced bids
+    if (a.id === synthetic.id) return 1;
+    if (b.id === synthetic.id) return -1;
+
+    // Regular tie-breaker: earlier bids rank higher
+    return new Date(a.created_at).getTime() - new Date(b.created_at).getTime();
+  });
+
+  const idx = sorted.findIndex((bid) => bid.id === synthetic.id);
+  if (idx === -1) return { rank: null, isWinning: false };
+
+  const rank = idx + 1;
+  const isWinning = rank <= maxTotalItems;
+  return { rank, isWinning };
+}
+
+export interface SuggestedBidsInput {
+  mergedForRank: RankableBid[];
+  maxTotalItems: number;
+  minBidValue: bigint;
+  reservePriceValue: bigint;
+  tickConfig: AuctionTickConfig | undefined;
+  tickSize?: bigint;
+}
+
+/**
+ * Generates an array of suggested bid prices based on the current leaderboard state.
+ * Returns 1-5 unique suggested prices in ascending order.
+ */
+export function getSuggestedBidPrices({
+  mergedForRank,
+  maxTotalItems,
+  minBidValue,
+  reservePriceValue,
+  tickConfig,
+  tickSize: tickSizeParam,
+}: SuggestedBidsInput): bigint[] {
+  const suggestions: bigint[] = [];
+
+  if (minBidValue <= 0n) {
+    return suggestions;
+  }
+
+  const fallbackTick =
+    tickSizeParam ?? (reservePriceValue > 0n ? reservePriceValue : minBidValue);
+
+  const tickAt = (priceValue: bigint): bigint =>
+    tickConfig ? getActiveTickSize(priceValue, tickConfig) : fallbackTick;
+
+  const ensureValid = (value: bigint): bigint =>
+    roundDownToValidBid(value, minBidValue, reservePriceValue, tickConfig);
+
+  // S1: minimum valid bid
+  suggestions.push(minBidValue);
+
+  const winning = mergedForRank.slice(0, maxTotalItems);
+
+  if (winning.length === 0) {
+    // No bids yet: use simple ladder above minBid
+    const base = minBidValue;
+    const t = tickAt(base);
+    suggestions.push(ensureValid(base + t));
+    suggestions.push(ensureValid(base + 3n * t));
+    suggestions.push(ensureValid(base + 5n * t));
+    return dedupeAndSortAscending(suggestions);
+  }
+
+  const lastWinning = winning[winning.length - 1];
+  const topWinning = winning[0];
+
+  const toValue = (bid: RankableBid): bigint => {
+    try {
+      return BigInt(bid.price);
+    } catch {
+      return minBidValue;
+    }
+  };
+
+  const lastWinningValue = toValue(lastWinning);
+  const topWinningValue = toValue(topWinning);
+
+  const upperIdxRaw = Math.floor(winning.length * 0.25);
+  const upperIdx = Math.min(
+    Math.max(upperIdxRaw, 0),
+    Math.max(winning.length - 1, 0),
+  );
+  const upperMidBid = winning[upperIdx];
+  const upperMidValue = toValue(upperMidBid);
+
+  suggestions.push(ensureValid(lastWinningValue + tickAt(lastWinningValue)));
+  suggestions.push(ensureValid(upperMidValue + tickAt(upperMidValue)));
+  suggestions.push(ensureValid(topWinningValue + tickAt(topWinningValue)));
+
+  return dedupeAndSortAscending(suggestions);
+}
+
+function dedupeAndSortAscending(values: bigint[]): bigint[] {
+  const uniq = Array.from(new Set(values.map((v) => v.toString()))).map((v) =>
+    BigInt(v),
+  );
+  return uniq.sort((a, b) => (a === b ? 0 : a > b ? 1 : -1));
+}

package/src/utils/tick-validation.ts

@@ -0,0 +1,65 @@
+import type { AuctionTickConfig } from "@/types";
+
+/**
+ * Returns the tick size to use for +/- steps based on the current bid.
+ * Threshold is EXCLUSIVE: bid must be strictly greater than threshold to use large tick.
+ */
+export function getActiveTickSize(
+  bidPrice: bigint,
+  tickConfig: AuctionTickConfig,
+): bigint {
+  return bidPrice > tickConfig.threshold
+    ? tickConfig.largeTickSize
+    : tickConfig.smallTickSize;
+}
+
+/**
+ * Checks if a bid price is on the auction's valid tick grid.
+ * Which tick applies is determined by the reference price (lowest possible bid:
+ * cutoff when full, else reserve), not by the user's bid.
+ */
+export function isValidTickPrice(
+  price: bigint,
+  reservePrice: bigint,
+  tickConfig: AuctionTickConfig | undefined,
+  referencePrice: bigint,
+): boolean {
+  if (!tickConfig) return true;
+  if (price < reservePrice) return false;
+
+  const { threshold, smallTickSize, largeTickSize } = tickConfig;
+  if (smallTickSize === 0n || largeTickSize === 0n) return false;
+
+  const activeTickSize = getActiveTickSize(referencePrice, tickConfig);
+  const base = activeTickSize === smallTickSize ? reservePrice : threshold;
+  return (price - base) % activeTickSize === 0n;
+}
+
+/**
+ * Returns the largest valid tick price that is <= price and >= minBid.
+ * Used when setPrice(price) is called so the displayed bid stays on the grid.
+ * When tickConfig is missing, returns minBid (single allowed value).
+ */
+export function roundDownToValidBid(
+  price: bigint,
+  minBid: bigint,
+  reservePrice: bigint,
+  tickConfig: AuctionTickConfig | undefined,
+): bigint {
+  if (price < minBid) return minBid;
+  if (!tickConfig) return minBid;
+
+  const { threshold, smallTickSize, largeTickSize } = tickConfig;
+  if (smallTickSize === 0n || largeTickSize === 0n) return minBid;
+
+  const activeTickSize = getActiveTickSize(price, tickConfig);
+  const base =
+    activeTickSize === smallTickSize ? reservePrice : threshold + smallTickSize;
+
+  if (price < base) return minBid;
+
+  const n = (price - base) / activeTickSize;
+  const candidate = base + n * activeTickSize;
+
+  return candidate >= minBid ? candidate : minBid;
+}