@pya-platform/ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @pya/ui
+
+## 0.1.0
+
+### Minor Changes
+
+- a9ca6bf: Initial release of the Pya platform packages. Extracted from `pyaeats-app`, consumed by `pyaeats-app` (food delivery) and `pyaserv` (services classifieds).
+
+  Each package exposes a Hono router factory (auth/cms/reviews/comments) or a typed helper (email/audit/cf) parameterised over Cloudflare D1 + KV bindings. UI primitives ship as Lit web components on top of `@pya/tokens` (CSS custom properties). See `ROADMAP.md` and `docs/phase-6-rollout.md` for the consumer cutover plan.
+
+### Patch Changes
+
+- Updated dependencies [a9ca6bf]
+  - @pya/tokens@0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pya-platform/ui",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/undeadliner/pya-platform.git"
+  },
+  "type": "module",
+  "description": "Lit web components shared across Pya projects — buttons, badges, cards, filter chips, quantity steppers, plus a11y/state controllers.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./components/*": "./src/components/*",
+    "./controllers/*": "./src/controllers/*",
+    "./helpers/*": "./src/helpers/*"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "echo '@pya/ui has no tests yet'"
+  },
+  "dependencies": {
+    "@pya-platform/tokens": "workspace:*",
+    "lit": "^3.2.1"
+  }
+}

package/src/components/pya-button/index.ts

@@ -0,0 +1,2 @@
+export { PyaButton } from './pya-button.ts'
+export { LOCATORS as PYA_BUTTON_LOCATORS } from './pya-button.locators.ts'

package/src/components/pya-button/pya-button.css

@@ -0,0 +1,76 @@
+/* Light-DOM styles for <pya-button>. Imported by sites consuming the component
+   (apps/site, apps/admin) via `import '@pyaeats/ui/components/pya-button/pya-button.css'`. */
+
+.pya-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--pya-space-2);
+  min-height: var(--pya-target-min);
+  padding-inline: var(--pya-space-4);
+  padding-block: var(--pya-space-2);
+  border: 2px solid transparent;
+  border-radius: var(--pya-radius-pill);
+  font: inherit;
+  font-weight: 700;
+  font-size: var(--pya-font-size-md);
+  text-align: center;
+  cursor: pointer;
+  transition: background-color var(--pya-motion-fast) var(--pya-ease-standard), transform
+    var(--pya-motion-fast) var(--pya-ease-standard);
+}
+
+/* Focus ring inherited from tokens/base.css via :where(button):focus-visible.
+   No override here — keep the soft halo consistent across the design system. */
+
+.pya-button[disabled] {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.pya-button--primary {
+  background: linear-gradient(135deg, var(--pya-acc), var(--pya-acc2));
+  color: var(--pya-text-on-acc);
+  box-shadow: 0 8px 20px color-mix(in srgb, var(--pya-acc2) 30%, transparent);
+}
+
+.pya-button--primary:hover:not([disabled]) {
+  transform: translateY(-1px);
+}
+.pya-button--primary:active:not([disabled]) {
+  transform: translateY(0);
+}
+
+.pya-button--ghost {
+  background: var(--pya-surface-2);
+  color: var(--pya-text);
+  border-color: var(--pya-border);
+}
+
+.pya-button--danger {
+  background: #c0392b;
+  color: #fff;
+}
+
+.pya-button--sm {
+  min-height: var(--pya-target-min);
+  padding-inline: var(--pya-space-3);
+  font-size: var(--pya-font-size-sm);
+}
+.pya-button--lg {
+  min-height: var(--pya-target-comfortable);
+  padding-inline: var(--pya-space-5);
+  font-size: var(--pya-font-size-lg);
+}
+
+@media (prefers-contrast: more) {
+  .pya-button {
+    border-width: 3px;
+    border-color: ButtonText;
+  }
+  .pya-button--primary {
+    background: Highlight;
+    color: HighlightText;
+    box-shadow: none;
+  }
+}

package/src/components/pya-button/pya-button.locators.ts

@@ -0,0 +1,4 @@
+/** Test-id constants for `<pya-button>`. Imported from both component and tests. */
+export const LOCATORS = {
+  root: 'pya-button',
+} as const

package/src/components/pya-button/pya-button.ts

@@ -0,0 +1,58 @@
+import { LitElement, css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { LOCATORS } from './pya-button.locators.ts'
+
+/**
+ * Accessible button primitive. Light DOM (a11y tree integrity, global token
+ * cascade). AAA: target ≥44px, 3px focus ring with 7:1 contrast, motion via
+ * --pya-motion-* tokens (auto-collapses under prefers-reduced-motion).
+ */
+@customElement('pya-button')
+export class PyaButton extends LitElement {
+  protected override createRenderRoot(): HTMLElement {
+    return this
+  }
+
+  @property({ type: String, reflect: true }) readonly variant: 'primary' | 'ghost' | 'danger' =
+    'primary'
+
+  @property({ type: String, reflect: true }) readonly size: 'sm' | 'md' | 'lg' = 'md'
+
+  @property({ type: Boolean, reflect: true }) readonly disabled = false
+
+  @property({ type: String, reflect: true }) readonly type: 'button' | 'submit' | 'reset' = 'button'
+
+  @property({ type: String }) readonly label = ''
+
+  static override styles = css`
+    /* light DOM — styles emitted via adoptedStyleSheets are still scoped. */
+  `
+
+  protected override render() {
+    return html`
+      <button
+        type=${this.type}
+        class=${`pya-button pya-button--${this.variant} pya-button--${this.size}`}
+        ?disabled=${this.disabled}
+        data-testid=${LOCATORS.root}
+        aria-label=${this.label || ''}
+        @click=${this.handleClick}
+      >
+        <slot></slot>
+      </button>
+    `
+  }
+
+  private readonly handleClick = (event: MouseEvent): void => {
+    if (this.disabled) {
+      event.preventDefault()
+      event.stopPropagation()
+    }
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'pya-button': PyaButton
+  }
+}

package/src/components/pya-cart-badge/index.ts

@@ -0,0 +1 @@
+export { PyaCartBadge } from './pya-cart-badge.ts'

package/src/components/pya-cart-badge/pya-cart-badge.css

@@ -0,0 +1,12 @@
+.pya-cart-badge {
+  display: inline-grid;
+  place-items: center;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 6px;
+  border-radius: var(--pya-radius-pill);
+  background: linear-gradient(135deg, var(--pya-acc), var(--pya-acc2));
+  color: var(--pya-text-on-acc);
+  font-size: 11px;
+  font-weight: 800;
+}

package/src/components/pya-cart-badge/pya-cart-badge.ts

@@ -0,0 +1,39 @@
+import { LitElement, html, nothing } from 'lit'
+import { customElement, state } from 'lit/decorators.js'
+import { cartStore } from '../../controllers/cart-store.ts'
+
+/** Live cart badge — subscribes to cartStore and announces changes. */
+@customElement('pya-cart-badge')
+export class PyaCartBadge extends LitElement {
+  protected override createRenderRoot(): HTMLElement {
+    return this
+  }
+
+  @state() private count = 0
+
+  private unsub?: () => void
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.count = cartStore.count()
+    this.unsub = cartStore.subscribe((state) => {
+      this.count = state.lines.reduce((s, l) => s + l.qty, 0)
+    })
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback()
+    this.unsub?.()
+  }
+
+  protected override render() {
+    if (this.count === 0) return nothing
+    return html`<span class="pya-cart-badge" aria-label=${`${this.count} artículo${this.count === 1 ? '' : 's'} en el carrito`}>${this.count}</span>`
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'pya-cart-badge': PyaCartBadge
+  }
+}

package/src/components/pya-filter-chip/index.ts

@@ -0,0 +1 @@
+export { PyaFilterChip } from './pya-filter-chip.ts'

package/src/components/pya-filter-chip/pya-filter-chip.css

@@ -0,0 +1,35 @@
+.pya-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--pya-space-2);
+  min-height: var(--pya-target-min);
+  padding: 8px 14px;
+  border: 1px solid var(--pya-border);
+  border-radius: var(--pya-radius-pill);
+  background: var(--pya-surface);
+  color: var(--pya-text);
+  font: inherit;
+  font-weight: 600;
+  font-size: var(--pya-font-size-sm);
+  cursor: pointer;
+  transition: background-color var(--pya-motion-fast) var(--pya-ease-standard);
+}
+/* Focus ring inherited from tokens/base.css. */
+.pya-chip[aria-pressed="true"] {
+  background: var(--pya-acc);
+  color: var(--pya-text-on-acc);
+  border-color: var(--pya-acc);
+}
+@media (prefers-contrast: more) {
+  .pya-chip {
+    border-width: 3px;
+    border-color: ButtonText;
+    background: ButtonFace;
+    color: ButtonText;
+  }
+  .pya-chip[aria-pressed="true"] {
+    background: Highlight;
+    color: HighlightText;
+    border-color: Highlight;
+  }
+}

package/src/components/pya-filter-chip/pya-filter-chip.ts

@@ -0,0 +1,43 @@
+import { LitElement, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+/** Multi-select filter chip. `<button aria-pressed>` pattern (per ARIA APG). */
+@customElement('pya-filter-chip')
+export class PyaFilterChip extends LitElement {
+  protected override createRenderRoot(): HTMLElement {
+    return this
+  }
+
+  @property({ type: Boolean, reflect: true }) pressed = false
+  @property({ type: String }) readonly label = ''
+  @property({ type: String }) readonly icon = ''
+
+  protected override render() {
+    return html`
+      <button
+        type="button"
+        class="pya-chip"
+        aria-pressed=${String(this.pressed)}
+        @click=${this.toggle}>
+        ${this.icon !== '' ? html`<span aria-hidden="true">${this.icon}</span>` : ''} ${this.label}
+      </button>
+    `
+  }
+
+  private readonly toggle = (): void => {
+    this.pressed = !this.pressed
+    this.dispatchEvent(
+      new CustomEvent('chip-toggle', {
+        detail: { pressed: this.pressed, label: this.label },
+        bubbles: true,
+        composed: true,
+      }),
+    )
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'pya-filter-chip': PyaFilterChip
+  }
+}

package/src/components/pya-quantity-stepper/index.ts

@@ -0,0 +1 @@
+export { PyaQuantityStepper } from './pya-quantity-stepper.ts'

package/src/components/pya-quantity-stepper/pya-quantity-stepper.css

@@ -0,0 +1,31 @@
+.pya-stepper {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--pya-space-2);
+}
+.pya-stepper__btn {
+  width: var(--pya-target-min);
+  height: var(--pya-target-min);
+  border-radius: var(--pya-radius-pill);
+  background: var(--pya-surface-2);
+  border: 1px solid var(--pya-border);
+  color: var(--pya-text);
+  font-size: var(--pya-font-size-lg);
+  font-weight: 700;
+  cursor: pointer;
+}
+/* Focus ring inherited from tokens/base.css. */
+.pya-stepper__btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+.pya-stepper__btn:active {
+  transform: scale(0.92);
+}
+.pya-stepper__value {
+  min-width: 24px;
+  text-align: center;
+  font-weight: 700;
+  font-size: var(--pya-font-size-md);
+  font-variant-numeric: tabular-nums;
+}

package/src/components/pya-quantity-stepper/pya-quantity-stepper.ts

@@ -0,0 +1,63 @@
+import { LitElement, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { announcer } from '../../controllers/announcer.ts'
+
+/** Accessible quantity stepper. Form-associated via ElementInternals. */
+@customElement('pya-quantity-stepper')
+export class PyaQuantityStepper extends LitElement {
+  static formAssociated = true
+  private readonly internals = this.attachInternals()
+
+  protected override createRenderRoot(): HTMLElement {
+    return this
+  }
+
+  @property({ type: Number }) value = 1
+  @property({ type: Number, attribute: 'min' }) readonly min = 1
+  @property({ type: Number, attribute: 'max' }) readonly max = 99
+  @property({ type: String }) readonly label = 'Cantidad'
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.internals.setFormValue(String(this.value))
+  }
+
+  protected override render() {
+    return html`
+      <div class="pya-stepper" role="group" aria-labelledby=${`stepper-label-${this.label}`}>
+        <span id=${`stepper-label-${this.label}`} class="visually-hidden">${this.label}</span>
+        <button type="button" class="pya-stepper__btn"
+                aria-label="Quitar uno"
+                ?disabled=${this.value <= this.min}
+                @click=${this.dec}>−</button>
+        <output class="pya-stepper__value" aria-live="polite">${this.value}</output>
+        <button type="button" class="pya-stepper__btn"
+                aria-label="Agregar uno"
+                ?disabled=${this.value >= this.max}
+                @click=${this.inc}>+</button>
+      </div>
+    `
+  }
+
+  private readonly inc = (): void => {
+    if (this.value >= this.max) return
+    this.value = this.value + 1
+    this.internals.setFormValue(String(this.value))
+    this.dispatchEvent(new CustomEvent('change', { detail: { value: this.value }, bubbles: true }))
+    announcer.announce(`Cantidad: ${this.value}`)
+  }
+
+  private readonly dec = (): void => {
+    if (this.value <= this.min) return
+    this.value = this.value - 1
+    this.internals.setFormValue(String(this.value))
+    this.dispatchEvent(new CustomEvent('change', { detail: { value: this.value }, bubbles: true }))
+    announcer.announce(`Cantidad: ${this.value}`)
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'pya-quantity-stepper': PyaQuantityStepper
+  }
+}

package/src/components/pya-store-card/index.ts

@@ -0,0 +1,2 @@
+export { PyaStoreCard } from './pya-store-card.ts'
+export { LOCATORS as PYA_STORE_CARD_LOCATORS } from './pya-store-card.locators.ts'

package/src/components/pya-store-card/pya-store-card.css

@@ -0,0 +1,126 @@
+.pya-card {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--pya-surface);
+  border: 1px solid var(--pya-border);
+  border-radius: var(--pya-radius-md);
+  box-shadow: var(--pya-shadow-sm);
+  text-decoration: none;
+  color: var(--pya-text);
+  transition: transform var(--pya-motion-fast) var(--pya-ease-standard);
+  /* Per-card VT name (injected via inline style by the renderer in
+     pages/index.astro + pages/stores/index.astro). When the user clicks a
+     card and the destination store page assigns the same name to its hero
+     cover, the browser morphs the rectangle into the cover. The thumb
+     fragment below grows from card-photo proportions to the 240px hero. */
+  /* Locked to the worst-case real card geometry (with 2 minitag pills) so
+     cards without optional pills don't shrink the row when they land. Skeleton
+     mirrors this exactly. 280 was too short — cards with both pills are 310. */
+  min-height: 310px;
+  box-sizing: border-box;
+}
+.pya-card:hover {
+  transform: translateY(-4px);
+  box-shadow: var(--pya-shadow);
+}
+/* Focus ring inherited from tokens/base.css. */
+
+.pya-card__photo {
+  height: 156px;
+  display: grid;
+  place-items: center;
+  font-size: 64px;
+  position: relative;
+  /* Per-card photo VT name injected by the renderer — paired with
+     .store-cover on the detail page (same slug). */
+}
+.pya-card__emoji {
+  line-height: 1;
+}
+.pya-card__tag {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  /* Dark translucent pill works over any gradient thumb and keeps AAA
+     contrast — earlier --pya-acc2 yellow on white failed WCAG AA. */
+  background: rgba(0, 0, 0, 0.72);
+  color: #fff;
+  font-size: var(--pya-font-size-xs);
+  font-weight: 700;
+  padding: 4px 10px;
+  border-radius: var(--pya-radius-pill);
+  backdrop-filter: blur(4px);
+}
+
+.pya-card__body {
+  padding: var(--pya-space-3) var(--pya-space-4) var(--pya-space-4);
+}
+.pya-card__row {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: var(--pya-space-2);
+}
+/* Explicit line-height = skeleton .pya-store-skel__name height (22px); the
+   browser default of ~1.4 made the real card 5px taller, which caused a CLS
+   spike on the skeleton → real swap. */
+.pya-card__name {
+  font-size: var(--pya-font-size-lg);
+  font-weight: 700;
+  margin: 0;
+  line-height: 22px;
+}
+.pya-card__rating {
+  background: color-mix(in srgb, var(--pya-acc) 16%, transparent);
+  color: var(--pya-acc);
+  padding: 2px 9px;
+  border-radius: var(--pya-radius-pill);
+  font-weight: 700;
+  font-size: var(--pya-font-size-sm);
+}
+.pya-card__meta {
+  color: var(--pya-text-muted);
+  font-size: var(--pya-font-size-sm);
+  margin: var(--pya-space-2) 0 0;
+}
+.pya-card__tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 7px;
+  margin-top: var(--pya-space-3);
+}
+.pya-minitag {
+  font-size: var(--pya-font-size-xs);
+  font-weight: 600;
+  padding: 4px 10px;
+  border-radius: var(--pya-radius-pill);
+  background: var(--pya-surface-2);
+  color: var(--pya-text-muted);
+}
+
+/* Food gradient thumbs — migrated from mockup. */
+.pya-thumb--burger {
+  background: linear-gradient(135deg, #ffd28a, #ff8a3d);
+}
+.pya-thumb--pizza {
+  background: linear-gradient(135deg, #ffb27a, #ef4f3a);
+}
+.pya-thumb--sushi {
+  background: linear-gradient(135deg, #a0e8c4, #16a34a);
+}
+.pya-thumb--taco {
+  background: linear-gradient(135deg, #ffe08a, #f59e0b);
+}
+.pya-thumb--chipa {
+  background: linear-gradient(135deg, #f7d9a8, #c98a3f);
+}
+.pya-thumb--asado {
+  background: linear-gradient(135deg, #ff9a76, #c0392b);
+}
+.pya-thumb--drink {
+  background: linear-gradient(135deg, #a5d8ff, #4c7ef3);
+}
+.pya-thumb--dessert {
+  background: linear-gradient(135deg, #ffc4e0, #e056a0);
+}

package/src/components/pya-store-card/pya-store-card.locators.ts

@@ -0,0 +1,6 @@
+export const LOCATORS = {
+  root: 'pya-store-card',
+  name: 'pya-store-card-name',
+  rating: 'pya-store-card-rating',
+  eta: 'pya-store-card-eta',
+} as const

package/src/components/pya-store-card/pya-store-card.ts

@@ -0,0 +1,61 @@
+import { LitElement, html, nothing } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { LOCATORS } from './pya-store-card.locators.ts'
+
+/** Photo-forward store card. Light DOM for a11y tree integrity. */
+@customElement('pya-store-card')
+export class PyaStoreCard extends LitElement {
+  protected override createRenderRoot(): HTMLElement {
+    return this
+  }
+
+  @property({ type: String, reflect: true }) readonly slug = ''
+  @property({ type: String }) readonly name = ''
+  @property({ type: String }) readonly cuisineLabel = ''
+  @property({ type: String }) readonly emoji = ''
+  @property({ type: String }) readonly thumb = 'burger'
+  @property({ type: Number }) readonly etaMin = 0
+  @property({ type: Number }) readonly etaMax = 0
+  @property({ type: Number }) readonly rating = 0
+  @property({ type: String }) readonly promo = ''
+  @property({ type: Boolean }) readonly express = false
+  @property({ type: Boolean }) readonly freeShipping = false
+  @property({ type: String }) readonly href = ''
+
+  protected override render() {
+    const ariaLabel = `${this.name}, ${this.cuisineLabel}, ${this.etaMin} a ${this.etaMax} minutos, calificación ${this.rating}`
+    // Per-slug VT names — matched by .store-cover on the detail page so the
+    // photo morphs into the hero cover during cross-document view-transition.
+    const cardVtName = `card-${this.slug}`
+    const photoVtName = `card-photo-${this.slug}`
+    return html`
+      <a class="pya-card" href=${this.href} data-testid=${LOCATORS.root} aria-label=${ariaLabel}
+         style=${`view-transition-name: ${cardVtName}`}>
+        <div class=${`pya-card__photo pya-thumb--${this.thumb}`} aria-hidden="true"
+             style=${`view-transition-name: ${photoVtName}`}>
+          <span class="pya-card__emoji">${this.emoji}</span>
+          ${this.promo !== '' ? html`<span class="pya-card__tag">${this.promo}</span>` : nothing}
+        </div>
+        <div class="pya-card__body">
+          <div class="pya-card__row">
+            <h3 class="pya-card__name" data-testid=${LOCATORS.name}>${this.name}</h3>
+            <span class="pya-card__rating" data-testid=${LOCATORS.rating}>★ ${this.rating}</span>
+          </div>
+          <p class="pya-card__meta">
+            ${this.cuisineLabel} · <span data-testid=${LOCATORS.eta}>${this.etaMin}–${this.etaMax} min</span>
+          </p>
+          <div class="pya-card__tags">
+            ${this.express ? html`<span class="pya-minitag">⚡ Express</span>` : nothing}
+            ${this.freeShipping ? html`<span class="pya-minitag">🛵 Gratis</span>` : nothing}
+          </div>
+        </div>
+      </a>
+    `
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'pya-store-card': PyaStoreCard
+  }
+}

package/src/controllers/announcer.ts

@@ -0,0 +1,29 @@
+/**
+ * Singleton accessible announcer. Owns two ARIA live regions in <body> (polite
+ * and assertive). Lit components call `announcer.announce(msg)` instead of
+ * creating their own live regions (which screen readers may not pick up if
+ * injected dynamically).
+ */
+const ensureRegion = (priority: 'polite' | 'assertive'): HTMLElement => {
+  const id = `pya-live-${priority}`
+  const existing = document.getElementById(id)
+  if (existing !== null) return existing
+  const el = document.createElement('div')
+  el.id = id
+  el.setAttribute('role', priority === 'polite' ? 'status' : 'alert')
+  el.setAttribute('aria-live', priority)
+  el.setAttribute('aria-atomic', 'true')
+  el.className = 'visually-hidden'
+  document.body.appendChild(el)
+  return el
+}
+
+export const announcer = {
+  announce(message: string, priority: 'polite' | 'assertive' = 'polite'): void {
+    const region = ensureRegion(priority)
+    region.textContent = ''
+    requestAnimationFrame(() => {
+      region.textContent = message
+    })
+  },
+}

package/src/controllers/cart-store.ts

@@ -0,0 +1,101 @@
+/**
+ * Cart store — client-side, localStorage-backed, pub/sub.
+ * Used by `<pya-cart-badge>`, `<pya-cart-drawer>`, and checkout page.
+ */
+const KEY = 'pya.cart'
+
+export interface CartLine {
+  readonly itemId: string
+  readonly name: string
+  readonly priceGs: number
+  readonly emoji?: string
+  readonly qty: number
+}
+
+export interface CartState {
+  readonly storeId?: string
+  readonly storeName?: string
+  readonly lines: ReadonlyArray<CartLine>
+}
+
+type Listener = (state: CartState) => void
+
+const isLine = (v: unknown): v is CartLine =>
+  typeof v === 'object' &&
+  v !== null &&
+  typeof (v as { itemId?: unknown }).itemId === 'string' &&
+  typeof (v as { name?: unknown }).name === 'string' &&
+  typeof (v as { priceGs?: unknown }).priceGs === 'number' &&
+  typeof (v as { qty?: unknown }).qty === 'number'
+
+const read = (): CartState => {
+  try {
+    const raw = globalThis.localStorage?.getItem(KEY)
+    if (raw === null || raw === undefined) return { lines: [] }
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null) return { lines: [] }
+    const obj = parsed as { storeId?: unknown; storeName?: unknown; lines?: unknown }
+    const lines = Array.isArray(obj.lines) ? obj.lines.filter(isLine) : []
+    const partial: CartState = { lines }
+    return typeof obj.storeId === 'string' && typeof obj.storeName === 'string'
+      ? { storeId: obj.storeId, storeName: obj.storeName, lines }
+      : partial
+  } catch {
+    return { lines: [] }
+  }
+}
+
+const listeners = new Set<Listener>()
+
+const write = (state: CartState): void => {
+  try {
+    globalThis.localStorage?.setItem(KEY, JSON.stringify(state))
+  } catch {
+    /* quota / SSR */
+  }
+  for (const l of listeners) l(state)
+}
+
+export const cartStore = {
+  read,
+  subscribe(listener: Listener): () => void {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  },
+  add(storeId: string, storeName: string, item: Omit<CartLine, 'qty'>, qty = 1): void {
+    const state = read()
+    if (state.storeId !== undefined && state.storeId !== storeId) {
+      // Single-store cart for MVP — replace if different store.
+      write({ storeId, storeName, lines: [{ ...item, qty }] })
+      return
+    }
+    const existing = state.lines.find((l) => l.itemId === item.itemId)
+    const lines = existing
+      ? state.lines.map((l) => (l.itemId === item.itemId ? { ...l, qty: l.qty + qty } : l))
+      : [...state.lines, { ...item, qty }]
+    write({ storeId, storeName, lines })
+  },
+  setQty(itemId: string, qty: number): void {
+    const state = read()
+    const lines = state.lines
+      .map((l) => (l.itemId === itemId ? { ...l, qty } : l))
+      .filter((l) => l.qty > 0)
+    write(lines.length === 0 ? { lines: [] } : { ...state, lines })
+  },
+  remove(itemId: string): void {
+    const state = read()
+    const lines = state.lines.filter((l) => l.itemId !== itemId)
+    write(lines.length === 0 ? { lines: [] } : { ...state, lines })
+  },
+  clear(): void {
+    write({ lines: [] })
+  },
+  count(): number {
+    return read().lines.reduce((s, l) => s + l.qty, 0)
+  },
+  subtotal(): number {
+    return read().lines.reduce((s, l) => s + l.priceGs * l.qty, 0)
+  },
+}

package/src/helpers/format-money.ts

@@ -0,0 +1,17 @@
+/** Pure UI helper for Guaraní formatting. Lit components import this rather
+ *  than reaching into @pya-platform/shared for tree-shaking on islands.
+ *  Locale read from <html lang> — Lit islands don't have framework context. */
+const isEnLocale = (): boolean =>
+  typeof document !== 'undefined' && document.documentElement.lang.startsWith('en')
+
+export const formatGs = (n: number): string => {
+  if (n === 0) return isEnLocale() ? 'Free' : 'Gratis'
+  return `Gs. ${n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, '.')}`
+}
+
+export const formatGsSpoken = (n: number): string => {
+  if (n === 0) return isEnLocale() ? 'free' : 'gratis'
+  const tag = isEnLocale() ? 'en-US' : 'es-PY'
+  const word = isEnLocale() ? 'guaraníes' : 'guaraníes'
+  return `${n.toLocaleString(tag)} ${word}`
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './components/pya-button/index.ts'
+export * from './components/pya-store-card/index.ts'
+export * from './components/pya-cart-badge/index.ts'
+export * from './components/pya-quantity-stepper/index.ts'
+export * from './components/pya-filter-chip/index.ts'
+export { announcer } from './controllers/announcer.ts'
+export { cartStore } from './controllers/cart-store.ts'
+export type { CartLine, CartState } from './controllers/cart-store.ts'
+export { formatGs, formatGsSpoken } from './helpers/format-money.ts'

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  },
+  "include": ["src/**/*.ts"]
+}