astro-component-kit 0.3.1 → 0.4.1

package/src/components/lib/ecommerce/VariantPicker.astro

@@ -0,0 +1,145 @@
+---
+/**
+ * VariantPicker — Colour swatches or size pills as an accessible radio group.
+ * Can keep an add-to-cart button's `data-variant` in sync with the selection.
+ *
+ * @param {string} label - Group legend. Default 'Colour'.
+ * @param {string} name - Radio name. Default 'variant'.
+ * @param {string} type - Picker style (swatch|pill). Default 'swatch'.
+ * @param {Array<{label: string, value?: string, hex?: string, disabled?: boolean}>} options - Choices.
+ * @param {number} selected - Index of the pre-selected option. Default 0.
+ * @param {string} target - id of an add-to-cart button whose `data-variant` follows the choice.
+ * @param {string} size - Control size (sm|md|lg). Default 'md'.
+ * @param {string} className - Extra class.
+ *
+ * Theming: --vp-active-bg, --vp-active-color, --vp-active-border, --vp-ring, --vp-radius.
+ *
+ * Accessibility: native radios (arrow keys work), visible focus ring, the chosen value is
+ * printed next to the legend; disabled options are announced as unavailable.
+ */
+interface Option { label: string; value?: string; hex?: string; disabled?: boolean }
+interface Props {
+  label?: string;
+  name?: string;
+  type?: 'swatch' | 'pill';
+  options?: Option[];
+  selected?: number;
+  target?: string;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+
+const {
+  label = 'Colour',
+  name = 'variant',
+  type = 'swatch',
+  options = [
+    { label: 'Graphite', hex: '#2b2b2f' },
+    { label: 'Sand', hex: '#d8c3a5' },
+    { label: 'Ocean', hex: '#3d6f9e' },
+    { label: 'Clay', hex: '#b5654a', disabled: true },
+  ],
+  selected = 0,
+  target,
+  size = 'md',
+  className = '',
+} = Astro.props;
+
+const uid = `vp-${name}`;
+---
+
+<fieldset class:list={['v-picker', `v-picker--${type}`, `v-picker--${size}`, className]} data-variant-picker data-target={target}>
+  <legend class="v-picker__legend">
+    {label}: <span class="v-picker__value" data-variant-value>{options[selected]?.label}</span>
+  </legend>
+  <div class="v-picker__options">
+    {options.map((o, i) => (
+      <label class:list={['v-picker__opt', { 'is-disabled': o.disabled }]} style={o.hex ? `--sw: ${o.hex}` : ''} title={o.label}>
+        <input
+          type="radio"
+          name={`${uid}`}
+          value={o.value ?? o.label}
+          data-label={o.label}
+          checked={i === selected}
+          disabled={o.disabled}
+        />
+        {type === 'swatch'
+          ? <span class="v-picker__dot" aria-hidden="true"></span>
+          : <span class="v-picker__pill">{o.label}</span>}
+        {type === 'swatch' && <span class="sr-only">{o.label}{o.disabled ? ' (sold out)' : ''}</span>}
+        {type === 'pill' && o.disabled && <span class="sr-only"> (sold out)</span>}
+      </label>
+    ))}
+  </div>
+</fieldset>
+
+<script>
+  document.querySelectorAll<HTMLFieldSetElement>('[data-variant-picker]:not([data-bound])').forEach((fs) => {
+    fs.dataset.bound = '';
+    const out = fs.querySelector<HTMLElement>('[data-variant-value]');
+    const sync = () => {
+      const checked = fs.querySelector<HTMLInputElement>('input:checked');
+      if (!checked) return;
+      if (out) out.textContent = checked.dataset.label || checked.value;
+      const btn = fs.dataset.target ? document.getElementById(fs.dataset.target) : null;
+      if (btn) {
+        // Combine every picker that targets the same button: "Sand / M"
+        const parts = Array.from(document.querySelectorAll<HTMLElement>(`[data-variant-picker][data-target="${fs.dataset.target}"]`))
+          .map((p) => p.querySelector<HTMLInputElement>('input:checked')?.dataset.label)
+          .filter(Boolean);
+        btn.dataset.variant = parts.join(' / ');
+      }
+    };
+    fs.addEventListener('change', sync);
+    sync();
+  });
+</script>
+
+<style>
+  .v-picker { margin: 0; padding: 0; border: 0; min-width: 0; }
+  .v-picker__legend { padding: 0; margin-bottom: var(--sp-3, 0.75rem); font-size: 0.85rem; font-weight: 600; color: var(--c-text-2, #a3a3a3); }
+  .v-picker__value { color: var(--c-text-1, #fff); }
+  .v-picker__options { display: flex; flex-wrap: wrap; gap: var(--sp-2, 0.5rem); }
+  .v-picker__opt { position: relative; cursor: pointer; }
+  .v-picker__opt input { position: absolute; opacity: 0; width: 1px; height: 1px; margin: 0; }
+  .v-picker__opt.is-disabled { cursor: not-allowed; }
+
+  .v-picker__dot {
+    display: block;
+    width: 36px;
+    height: 36px;
+    margin: 4px;
+    border-radius: 50%;
+    background: var(--sw);
+    box-shadow: 0 0 0 1px rgb(var(--ink-rgb, 255 255 255) / 0.2);
+    transition: box-shadow 0.15s ease, transform 0.15s ease;
+  }
+  .v-picker--sm .v-picker__dot { width: 28px; height: 28px; margin: 8px; }
+  .v-picker--lg .v-picker__dot { width: 44px; height: 44px; margin: 2px; }
+  .v-picker__opt:hover .v-picker__dot { transform: scale(1.06); }
+  .v-picker__opt input:checked + .v-picker__dot { box-shadow: 0 0 0 3px var(--c-bg, #050505), 0 0 0 5px var(--vp-ring, var(--c-primary-light, #d4a017)); }
+  .v-picker__opt.is-disabled .v-picker__dot { opacity: 0.35; background-image: linear-gradient(135deg, transparent 46%, rgb(var(--ink-rgb, 255 255 255) / 0.8) 47% 53%, transparent 54%); }
+
+  .v-picker__pill {
+    display: grid;
+    place-items: center;
+    min-width: 52px;
+    min-height: 44px;
+    padding: 0 var(--sp-4, 1rem);
+    border-radius: var(--vp-radius, var(--r-md, 12px));
+    border: 1px solid rgb(var(--ink-rgb, 255 255 255) / 0.12);
+    color: var(--c-text-1, #fff);
+    font-size: 0.88rem;
+    font-weight: 600;
+    transition: border-color 0.15s ease, background 0.15s ease;
+  }
+  .v-picker--sm .v-picker__pill { min-height: 36px; min-width: 44px; font-size: 0.8rem; }
+  .v-picker__opt:hover .v-picker__pill { border-color: rgb(var(--ink-rgb, 255 255 255) / 0.3); }
+  .v-picker__opt input:checked + .v-picker__pill { border-color: var(--vp-active-border, var(--c-primary-light, #d4a017)); background: var(--vp-active-bg, rgba(212, 160, 23, 0.12)); color: var(--vp-active-color, var(--c-text-1, #fff)); }
+  .v-picker__opt.is-disabled .v-picker__pill { color: var(--c-text-3, #737373); text-decoration: line-through; }
+
+  .v-picker__opt input:focus-visible + .v-picker__dot,
+  .v-picker__opt input:focus-visible + .v-picker__pill { outline: 2px solid var(--c-primary-light, #d4a017); outline-offset: 3px; }
+
+  .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+</style>

package/src/components/lib/ecommerce/cart-store.ts

@@ -0,0 +1,151 @@
+// src/components/lib/ecommerce/cart-store.ts
+// Tiny framework-free cart store shared by every e-commerce component.
+//
+// - Persists to localStorage (per `storageKey`), falls back to memory when storage is blocked.
+// - Broadcasts `ack:cart` on `document` after every change, and syncs across tabs.
+// - `formatMoney` is pure and also safe to call at build time.
+
+import type { CartItem, MoneyFormat } from './types';
+
+export const CART_EVENT = 'ack:cart';
+/** Fired after an add-to-cart button adds an item: `{ key, item, openCart }`. */
+export const ADDED_EVENT = 'ack:cart-added';
+/** Fire this to show any notice in CartToast: `{ title, text?, tone?: 'info'|'success'|'warning'|'danger' }`. */
+export const NOTIFY_EVENT = 'ack:notify';
+const DEFAULT_KEY = 'ack-cart';
+
+const memory: Record<string, CartItem[]> = {};
+
+export function formatMoney(value: number, { currency = 'USD', locale = 'en-US' }: MoneyFormat = {}): string {
+  try {
+    return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(value);
+  } catch {
+    return `${value.toFixed(2)} ${currency}`;
+  }
+}
+
+function read(key: string): CartItem[] {
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed.filter((i) => i && typeof i.id === 'string');
+    }
+    return memory[key] ?? [];
+  } catch {
+    return memory[key] ?? [];
+  }
+}
+
+function write(key: string, items: CartItem[]): void {
+  memory[key] = items;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(items));
+  } catch {
+    /* storage blocked — memory copy is enough for this page view */
+  }
+  document.dispatchEvent(new CustomEvent(CART_EVENT, { detail: { key, items } }));
+}
+
+/** Line id: product id + variant, so "Tee / M" and "Tee / L" are separate lines. */
+export function lineId(id: string, variant?: string): string {
+  return variant ? `${id}::${variant}` : id;
+}
+
+export function createCart(storageKey: string = DEFAULT_KEY) {
+  const api = {
+    key: storageKey,
+    items: (): CartItem[] => read(storageKey),
+    count: (): number => read(storageKey).reduce((n, i) => n + i.qty, 0),
+    subtotal: (): number => read(storageKey).reduce((n, i) => n + i.price * i.qty, 0),
+    add(item: Omit<CartItem, 'qty'> & { qty?: number }): void {
+      const items = read(storageKey);
+      const id = lineId(item.id, item.variant);
+      const existing = items.find((i) => i.id === id);
+      if (existing) existing.qty = Math.min(99, existing.qty + (item.qty ?? 1));
+      else items.push({ ...item, id, qty: Math.max(1, item.qty ?? 1) });
+      write(storageKey, items);
+    },
+    setQty(id: string, qty: number): void {
+      const items = read(storageKey)
+        .map((i) => (i.id === id ? { ...i, qty: Math.min(99, Math.max(0, Math.round(qty))) } : i))
+        .filter((i) => i.qty > 0);
+      write(storageKey, items);
+    },
+    remove(id: string): void {
+      write(storageKey, read(storageKey).filter((i) => i.id !== id));
+    },
+    clear(): void {
+      write(storageKey, []);
+    },
+    /** Fills an empty cart once (demo stores). Never overwrites a real cart. */
+    seed(items: CartItem[]): void {
+      const flag = `${storageKey}:seeded`;
+      try {
+        if (window.localStorage.getItem(flag)) return;
+        window.localStorage.setItem(flag, '1');
+      } catch {
+        if (memory[flag]) return;
+        memory[flag] = [];
+      }
+      if (read(storageKey).length === 0 && items.length) write(storageKey, items);
+    },
+    subscribe(fn: (items: CartItem[]) => void): () => void {
+      const onLocal = (e: Event) => {
+        const detail = (e as CustomEvent).detail;
+        if (!detail || detail.key === storageKey) fn(read(storageKey));
+      };
+      const onStorage = (e: StorageEvent) => {
+        if (e.key === storageKey) fn(read(storageKey));
+      };
+      document.addEventListener(CART_EVENT, onLocal);
+      window.addEventListener('storage', onStorage);
+      return () => {
+        document.removeEventListener(CART_EVENT, onLocal);
+        window.removeEventListener('storage', onStorage);
+      };
+    },
+  };
+  return api;
+}
+
+export type Cart = ReturnType<typeof createCart>;
+
+/**
+ * Wires every `[data-add-to-cart]` button inside `root` to the cart.
+ * The attribute holds the item JSON; an optional `data-cart-key` picks the store.
+ * Variant pickers can update `data-variant` on the button before the click.
+ */
+export function bindAddToCart(root: ParentNode = document): void {
+  root.querySelectorAll<HTMLButtonElement>('[data-add-to-cart]:not([data-cart-bound])').forEach((btn) => {
+    btn.dataset.cartBound = '';
+    btn.addEventListener('click', (event) => {
+      event.preventDefault();
+      let item: CartItem;
+      try {
+        item = JSON.parse(btn.dataset.addToCart || '{}');
+      } catch {
+        return;
+      }
+      if (!item.id) return;
+      const qtyInput = btn.dataset.qtyFrom ? document.getElementById(btn.dataset.qtyFrom) as HTMLInputElement | null : null;
+      const qty = qtyInput ? Number(qtyInput.value) || 1 : 1;
+      const added = { ...item, variant: btn.dataset.variant || item.variant, qty };
+      createCart(btn.dataset.cartKey || DEFAULT_KEY).add(added);
+      document.dispatchEvent(new CustomEvent(ADDED_EVENT, { detail: { key: btn.dataset.cartKey || DEFAULT_KEY, item: added, openCart: btn.dataset.openCart !== 'false' } }));
+
+      const label = btn.querySelector<HTMLElement>('[data-label]');
+      const original = label?.textContent;
+      btn.classList.add('is-added');
+      if (label && btn.dataset.addedLabel) label.textContent = btn.dataset.addedLabel;
+      window.setTimeout(() => {
+        btn.classList.remove('is-added');
+        if (label && original) label.textContent = original;
+      }, 1400);
+
+      if (btn.dataset.openCart !== 'false') {
+        document.dispatchEvent(new CustomEvent('ack:cart-open', { detail: { key: btn.dataset.cartKey || DEFAULT_KEY } }));
+      }
+    });
+  });
+}

package/src/components/lib/ecommerce/catalog-filter.ts

@@ -0,0 +1,62 @@
+// src/components/lib/ecommerce/catalog-filter.ts
+// Client-side filter + sort for any grid of `[data-product]` cards
+// (StoreProductCard and ProductCardMinimal both expose the same data attributes).
+
+export interface CatalogState {
+  categories: string[];
+  colors: string[];
+  maxPrice: number;
+  minRating: number;
+  inStockOnly: boolean;
+  sort: 'featured' | 'price-asc' | 'price-desc' | 'rating' | 'name' | string;
+}
+
+/** Filters and re-orders the cards inside `grid`. Returns the number of visible cards. */
+export function applyCatalogFilter(grid: HTMLElement, state: CatalogState): number {
+  const cards = Array.from(grid.querySelectorAll<HTMLElement>('[data-product]'));
+  cards.forEach((c, i) => { if (c.dataset.index === undefined) c.dataset.index = String(i); });
+  let visible = 0;
+
+  for (const card of cards) {
+    const d = card.dataset;
+    const colors = (d.colors || '').split(',').filter(Boolean);
+    const ok =
+      (!state.categories.length || state.categories.includes(d.category || '')) &&
+      Number(d.price) <= state.maxPrice &&
+      Number(d.rating || 0) >= state.minRating &&
+      (!state.inStockOnly || d.stock === 'in') &&
+      (!state.colors.length || state.colors.some((c) => colors.includes(c)));
+    // Cards may be wrapped (e.g. in <li>): hide the direct child of the grid.
+    const item = card.parentElement === grid ? card : (card.closest(`#${CSS.escape(grid.id)} > *`) as HTMLElement | null) ?? card;
+    item.hidden = !ok;
+    if (ok) visible++;
+  }
+
+  const items = cards.map((card) => ({ card, item: card.parentElement === grid ? card : ((card.closest(`#${CSS.escape(grid.id)} > *`) as HTMLElement | null) ?? card) }));
+  items.sort((a, b) => {
+    const A = a.card.dataset, B = b.card.dataset;
+    switch (state.sort) {
+      case 'price-asc': return Number(A.price) - Number(B.price);
+      case 'price-desc': return Number(B.price) - Number(A.price);
+      case 'rating': return Number(B.rating) - Number(A.rating);
+      case 'name': return (A.name || '').localeCompare(B.name || '');
+      default: return Number(A.index) - Number(B.index);
+    }
+  });
+  grid.append(...items.map((i) => i.item));
+
+  const empty = grid.parentElement?.querySelector<HTMLElement>('[data-product-empty]');
+  if (empty) empty.hidden = visible > 0;
+  document.querySelectorAll<HTMLElement>(`[data-result-count="${grid.id}"]`).forEach((n) => { n.textContent = String(visible); });
+  return visible;
+}
+
+/** Reads/writes `?category=` and `?sort=` so filtered views can be shared. */
+export function syncCatalogUrl(state: Pick<CatalogState, 'categories' | 'sort'>): void {
+  const url = new URL(window.location.href);
+  if (state.categories.length) url.searchParams.set('category', state.categories.join(','));
+  else url.searchParams.delete('category');
+  if (state.sort && state.sort !== 'featured') url.searchParams.set('sort', state.sort);
+  else url.searchParams.delete('sort');
+  window.history.replaceState(null, '', url);
+}

package/src/components/lib/ecommerce/index.ts

@@ -0,0 +1,34 @@
+// src/components/lib/ecommerce/index.ts
+// Barrel export for e-commerce components (shop UI + client cart store).
+
+export { default as ProductMedia } from './ProductMedia.astro';
+export { default as ProductRating } from './ProductRating.astro';
+export { default as StoreProductCard } from './StoreProductCard.astro';
+export { default as ProductGrid } from './ProductGrid.astro';
+export { default as PromoBar } from './PromoBar.astro';
+export { default as StoreHeader } from './StoreHeader.astro';
+export { default as CartDrawer } from './CartDrawer.astro';
+export { default as StoreHero } from './StoreHero.astro';
+export { default as CategoryTiles } from './CategoryTiles.astro';
+export { default as TrustBadges } from './TrustBadges.astro';
+export { default as FilterSidebar } from './FilterSidebar.astro';
+export { default as ProductToolbar } from './ProductToolbar.astro';
+export { default as ProductGallery } from './ProductGallery.astro';
+export { default as VariantPicker } from './VariantPicker.astro';
+export { default as ProductBuyBox } from './ProductBuyBox.astro';
+export { default as OrderSummary } from './OrderSummary.astro';
+export { default as CheckoutForm } from './CheckoutForm.astro';
+export { default as CartToast } from './CartToast.astro';
+export { default as LiveActivityToast } from './LiveActivityToast.astro';
+export { default as CountdownBanner } from './CountdownBanner.astro';
+export { default as StockIndicator } from './StockIndicator.astro';
+export { default as ProductCardMinimal } from './ProductCardMinimal.astro';
+export { default as FilterBar } from './FilterBar.astro';
+export { default as CartPageList } from './CartPageList.astro';
+
+export { createCart, bindAddToCart, formatMoney, lineId, CART_EVENT, ADDED_EVENT, NOTIFY_EVENT } from './cart-store';
+export { applyCatalogFilter, syncCatalogUrl } from './catalog-filter';
+export type { CatalogState } from './catalog-filter';
+export { productIcons, productIcon } from './product-icons';
+export type { ProductIcon } from './product-icons';
+export type { Product, ProductColor, StoreCategory, CartItem, ShippingRate, MoneyFormat } from './types';

package/src/components/lib/ecommerce/product-icons.ts

@@ -0,0 +1,28 @@
+// src/components/lib/ecommerce/product-icons.ts
+// Line-art product illustrations (64×64 viewBox, stroke = currentColor).
+// Used by ProductMedia so demo stores look finished without any external images.
+
+export const productIcons = {
+  headphones: '<path d="M12 38v-6a20 20 0 0 1 40 0v6"/><rect x="8" y="36" width="10" height="16" rx="4"/><rect x="46" y="36" width="10" height="16" rx="4"/><path d="M18 44h-2M46 44h2"/>',
+  watch: '<rect x="18" y="18" width="28" height="28" rx="9"/><path d="M24 18l2-10h12l2 10M24 46l2 10h12l2-10"/><path d="M32 25v7l5 4"/><path d="M46 30h3"/>',
+  sneaker: '<path d="M6 44c0-6 2-14 6-20l8 4c3 2 7 2 10 0l4-3c6 8 14 11 22 12 2 0 3 2 3 4v3H6z"/><path d="M6 47v3h53v-3"/><path d="M22 30l3 4M27 28l3 4M32 26l2 4"/>',
+  backpack: '<rect x="14" y="16" width="36" height="42" rx="10"/><path d="M24 16v-4a8 8 0 0 1 16 0v4"/><rect x="21" y="36" width="22" height="13" rx="4"/><path d="M21 42h22"/>',
+  camera: '<rect x="6" y="18" width="52" height="34" rx="7"/><path d="M22 18l4-7h12l4 7"/><circle cx="32" cy="35" r="10"/><circle cx="32" cy="35" r="4"/><path d="M48 25h3"/>',
+  lamp: '<path d="M20 10h24l8 20H12z"/><path d="M32 30v20"/><path d="M20 56h24"/><path d="M26 50h12"/>',
+  keyboard: '<rect x="4" y="20" width="56" height="26" rx="5"/><path d="M11 28h3M19 28h3M27 28h3M35 28h3M43 28h3M51 28h2M13 35h3M21 35h3M29 35h3M37 35h3M45 35h4M18 41h28"/>',
+  sunglasses: '<path d="M4 26h56"/><path d="M8 26c0 9 3 14 10 14s10-5 10-14"/><path d="M36 26c0 9 3 14 10 14s10-5 10-14"/><path d="M28 30c2-2 6-2 8 0"/>',
+  bottle: '<path d="M26 6h12v8l4 6v34a4 4 0 0 1-4 4H26a4 4 0 0 1-4-4V20l4-6z"/><path d="M22 28h20M22 44h20"/>',
+  speaker: '<rect x="16" y="6" width="32" height="52" rx="8"/><circle cx="32" cy="38" r="10"/><circle cx="32" cy="38" r="3"/><circle cx="32" cy="17" r="4"/>',
+  jacket: '<path d="M22 8l10 6 10-6 12 8 4 22-8 2v18H14V40l-8-2 4-22z"/><path d="M32 14v42"/><path d="M22 8l-2 12 6 6M42 8l2 12-6 6"/><path d="M38 34h4M38 42h4"/>',
+  mug: '<path d="M12 18h32v28a8 8 0 0 1-8 8H20a8 8 0 0 1-8-8z"/><path d="M44 24h4a6 6 0 0 1 0 12h-4"/><path d="M22 8c-2 3 2 4 0 7M30 8c-2 3 2 4 0 7"/>',
+  plant: '<path d="M20 40h24l-3 18H23z"/><path d="M32 40V22"/><path d="M32 30c-8 0-12-6-12-14 8 0 12 6 12 14zM32 26c0-8 4-14 12-14 0 8-4 14-12 14z"/>',
+  shirt: '<path d="M22 8l-14 8 5 12 7-3v31h24V25l7 3 5-12-14-8c-1 4-5 6-10 6s-9-2-10-6z"/>',
+  bag: '<path d="M12 22h40l-4 34H16z"/><path d="M24 22v-6a8 8 0 0 1 16 0v6"/><path d="M24 30v2M40 30v2"/>',
+  phone: '<rect x="18" y="4" width="28" height="56" rx="7"/><path d="M28 10h8"/><circle cx="32" cy="52" r="2"/>',
+} as const;
+
+export type ProductIcon = keyof typeof productIcons;
+
+export function productIcon(name?: string): string {
+  return productIcons[(name as ProductIcon) ?? 'bag'] ?? productIcons.bag;
+}

package/src/components/lib/ecommerce/types.ts

@@ -0,0 +1,70 @@
+// src/components/lib/ecommerce/types.ts
+// Shared data shapes for the e-commerce components and the store template.
+
+import type { ProductIcon } from './product-icons';
+
+export interface ProductColor {
+  name: string;
+  hex: string;
+}
+
+export interface Product {
+  /** URL-safe id, also used as cart line id. */
+  slug: string;
+  name: string;
+  /** Price in major units (e.g. 129.9). */
+  price: number;
+  /** Optional "before" price, shown struck through. */
+  compareAt?: number;
+  /** Category id (matches `StoreCategory.id`). */
+  category: string;
+  /** 0–5 average rating. */
+  rating?: number;
+  reviews?: number;
+  /** Short highlight such as "New" or "-20%". */
+  badge?: string;
+  badgeVariant?: 'default' | 'success' | 'warning' | 'danger' | 'info';
+  colors?: ProductColor[];
+  sizes?: string[];
+  /** Built-in illustration used when no `image` is given. */
+  icon?: ProductIcon;
+  /** Hue (0–360) of the generated product backdrop. */
+  hue?: number;
+  /** Real product photo; replaces the illustration. */
+  image?: string;
+  description?: string;
+  inStock?: boolean;
+  /** Units left; StockIndicator shows urgency at or below its threshold. */
+  stock?: number;
+}
+
+export interface StoreCategory {
+  id: string;
+  name: string;
+  description?: string;
+  icon?: ProductIcon;
+  hue?: number;
+}
+
+export interface CartItem {
+  id: string;
+  name: string;
+  price: number;
+  qty: number;
+  variant?: string;
+  image?: string;
+  icon?: ProductIcon;
+  hue?: number;
+}
+
+export interface ShippingRate {
+  id: string;
+  label: string;
+  eta: string;
+  price: number;
+}
+
+export interface MoneyFormat {
+  currency?: string;
+  locale?: string;
+}

package/src/components/lib/feedback/ProgressRingCounter.astro

@@ -0,0 +1,118 @@
+---
+/**
+ * ProgressRingCounter — Circular SVG progress ring with centered countdown or metric value.
+ * 
+ * @param {number} value - Current counter or progress value. Default is 75.
+ * @param {number} max - Maximum value threshold. Default is 100.
+ * @param {number} size - Pixel diameter of the ring. Default is 96.
+ * @param {number} strokeWidth - Thickness of the ring stroke. Default is 6.
+ * @param {string} color - Primary gauge fill color. Default is '#d4a017'.
+ * @param {string} label - Subtitle label beneath figure. Default is 'COMPLETED'.
+ */
+interface Props {
+  value?: number;
+  max?: number;
+  size?: number;
+  strokeWidth?: number;
+  color?: string;
+  label?: string;
+}
+
+const {
+  value = 75,
+  max = 100,
+  size = 96,
+  strokeWidth = 6,
+  color = '#d4a017',
+  label = 'COMPLETED',
+} = Astro.props;
+
+const radius = (size - strokeWidth) / 2;
+const circumference = 2 * Math.PI * radius;
+const percent = Math.min(100, Math.max(0, (value / max) * 100));
+const strokeDashoffset = circumference - (percent / 100) * circumference;
+---
+
+<div class="ring-counter" style={`--ring-size: ${size}px; --ring-color: ${color};`}>
+  <svg width={size} height={size} class="ring-counter__svg">
+    <circle
+      class="ring-counter__bg"
+      cx={size / 2}
+      cy={size / 2}
+      r={radius}
+      stroke-width={strokeWidth}
+    />
+    <circle
+      class="ring-counter__meter"
+      cx={size / 2}
+      cy={size / 2}
+      r={radius}
+      stroke-width={strokeWidth}
+      stroke-dasharray={circumference}
+      stroke-dashoffset={strokeDashoffset}
+    />
+  </svg>
+
+  <div class="ring-counter__center">
+    <span class="val">{Math.round(percent)}%</span>
+    {label && <span class="lbl">{label}</span>}
+  </div>
+</div>
+
+<style>
+  .ring-counter {
+    position: relative;
+    width: var(--ring-size);
+    height: var(--ring-size);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-family: var(--font-sans, system-ui, sans-serif);
+    user-select: none;
+  }
+
+  .ring-counter__svg {
+    transform: rotate(-90deg);
+    width: 100%;
+    height: 100%;
+  }
+
+  .ring-counter__bg {
+    fill: none;
+    stroke: rgba(255, 255, 255, 0.08);
+  }
+
+  .ring-counter__meter {
+    fill: none;
+    stroke: var(--ring-color);
+    stroke-linecap: round;
+    transition: stroke-dashoffset 0.8s cubic-bezier(0.16, 1, 0.3, 1);
+    filter: drop-shadow(0 0 6px rgba(212, 160, 23, 0.35));
+  }
+
+  .ring-counter__center {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+  }
+
+  .ring-counter__center .val {
+    font-size: 1.25rem;
+    font-weight: 800;
+    color: var(--c-text-1, #ffffff);
+    line-height: 1;
+  }
+
+  .ring-counter__center .lbl {
+    font-size: 0.55rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    color: var(--c-text-3, #737373);
+    margin-top: 4px;
+    text-transform: uppercase;
+  }
+</style>