@vtex/faststore 0.0.1

package/dist/particles/popover/popover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.js","names":["BasePopover","Popover"],"sources":["../../../src/particles/popover/popover.tsx"],"sourcesContent":["'use client';\nimport { Popover as BasePopover } from '@base-ui/react/popover';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef, ReactNode } from 'react';\n\nexport type PopoverSide = 'top' | 'bottom' | 'left' | 'right';\nexport type PopoverAlign = 'start' | 'center' | 'end';\n\nexport type PopoverRootProps = {\n  defaultOpen?: boolean;\n  modal?: boolean;\n  children?: ReactNode;\n};\n\nexport type PopoverTriggerProps = ComponentPropsWithRef<'button'> & {\n  openOnHover?: boolean;\n  delay?: number;\n  closeDelay?: number;\n};\n\nexport type PopoverPortalProps = {\n  children?: ReactNode;\n};\n\nexport type PopoverBackdropProps = ComponentPropsWithRef<'div'>;\n\nexport type PopoverPositionerProps = ComponentPropsWithRef<'div'> & {\n  side?: PopoverSide;\n  align?: PopoverAlign;\n  sideOffset?: number;\n};\n\nexport type PopoverPopupProps = ComponentPropsWithRef<'div'>;\n\nexport type PopoverArrowProps = ComponentPropsWithRef<'div'>;\n\nexport type PopoverViewportProps = ComponentPropsWithRef<'div'>;\n\nexport type PopoverTitleProps = ComponentPropsWithRef<'h2'>;\n\nexport type PopoverDescriptionProps = ComponentPropsWithRef<'p'>;\n\nexport type PopoverCloseProps = ComponentPropsWithRef<'button'>;\n\nexport const PopoverRootDefinition = defineComponent<PopoverRootProps>({\n  name: 'PopoverRoot',\n  importPath: '@vtex/faststore/components',\n  component: PopoverRoot,\n  editor: { label: 'Popover Root', category: 'layout' },\n  schema: {\n    defaultOpen: { type: 'boolean', default: false, label: 'Default Open' },\n    modal: { type: 'boolean', default: false, label: 'Modal' },\n  },\n  guideline:\n    'Root of an anchored overlay for rich content (forms, product previews). Manages open state and focus trapping. Compose as: PopoverRoot > (PopoverTrigger + PopoverPortal > (PopoverBackdrop + PopoverPositioner > PopoverPopup > (PopoverArrow + PopoverTitle + PopoverDescription + content + PopoverClose))). Set modal=true when content requires focus trap.',\n});\n\nexport const PopoverTriggerDefinition = defineComponent<PopoverTriggerProps>({\n  name: 'PopoverTrigger',\n  importPath: '@vtex/faststore/components',\n  component: PopoverTrigger,\n  editor: { label: 'Popover Trigger', category: 'action' },\n  schema: {\n    openOnHover: { type: 'boolean', default: false, label: 'Open On Hover' },\n    delay: { type: 'number', default: 300, label: 'Delay' },\n    closeDelay: { type: 'number', default: 0, label: 'Close Delay' },\n  },\n  guideline: 'Set openOnHover=true for instant preview panels on product cards or image thumbnails.',\n});\n\nexport const PopoverPortalDefinition = defineComponent<PopoverPortalProps>({\n  name: 'PopoverPortal',\n  importPath: '@vtex/faststore/components',\n  component: PopoverPortal,\n  editor: { label: 'Popover Portal', category: 'layout' },\n  schema: {},\n  guideline: 'Teleports popover content to <body> to avoid overflow/z-index issues.',\n});\n\nexport const PopoverBackdropDefinition = defineComponent<PopoverBackdropProps>({\n  name: 'PopoverBackdrop',\n  importPath: '@vtex/faststore/components',\n  component: PopoverBackdrop,\n  editor: { label: 'Popover Backdrop', category: 'layout' },\n  schema: {},\n  guideline: 'Semi-transparent overlay rendered behind the popup when modal=true.',\n});\n\nexport const PopoverPositionerDefinition = defineComponent<PopoverPositionerProps>({\n  name: 'PopoverPositioner',\n  importPath: '@vtex/faststore/components',\n  component: PopoverPositioner,\n  editor: { label: 'Popover Positioner', category: 'layout' },\n  schema: {\n    side: { type: ['top', 'bottom', 'left', 'right'] as const, default: 'bottom', label: 'Side' },\n    align: { type: ['start', 'center', 'end'] as const, default: 'center', label: 'Align' },\n    sideOffset: { type: 'number', default: 0, label: 'Side Offset' },\n  },\n  guideline: 'Controls popup placement relative to the trigger.',\n});\n\nexport const PopoverPopupDefinition = defineComponent<PopoverPopupProps>({\n  name: 'PopoverPopup',\n  importPath: '@vtex/faststore/components',\n  component: PopoverPopup,\n  editor: { label: 'Popover Popup', category: 'layout' },\n  schema: {},\n  guideline: 'Main popover content container. Always include Popover.Title for screen reader accessibility.',\n});\n\nexport const PopoverArrowDefinition = defineComponent<PopoverArrowProps>({\n  name: 'PopoverArrow',\n  importPath: '@vtex/faststore/components',\n  component: PopoverArrow,\n  editor: { label: 'Popover Arrow', category: 'layout' },\n  schema: {},\n  guideline: 'Pointing arrow attached to the popup. Optional — omit when not using an arrow indicator.',\n});\n\nexport const PopoverViewportDefinition = defineComponent<PopoverViewportProps>({\n  name: 'PopoverViewport',\n  importPath: '@vtex/faststore/components',\n  component: PopoverViewport,\n  editor: { label: 'Popover Viewport', category: 'layout' },\n  schema: {},\n  guideline: 'Viewport wrapper inside Popover.Popup for constraining content display area.',\n});\n\nexport const PopoverTitleDefinition = defineComponent<PopoverTitleProps>({\n  name: 'PopoverTitle',\n  importPath: '@vtex/faststore/components',\n  component: PopoverTitle,\n  editor: { label: 'Popover Title', category: 'layout' },\n  schema: {},\n  guideline: 'Accessible heading inside Popover.Popup. Sets the accessible name of the popover dialog.',\n});\n\nexport const PopoverDescriptionDefinition = defineComponent<PopoverDescriptionProps>({\n  name: 'PopoverDescription',\n  importPath: '@vtex/faststore/components',\n  component: PopoverDescription,\n  editor: { label: 'Popover Description', category: 'layout' },\n  schema: {},\n  guideline: 'Accessible description of the popover content. Announced by screen readers.',\n});\n\nexport const PopoverCloseDefinition = defineComponent<PopoverCloseProps>({\n  name: 'PopoverClose',\n  importPath: '@vtex/faststore/components',\n  component: PopoverClose,\n  editor: { label: 'Popover Close', category: 'action' },\n  schema: {},\n  guideline: 'Button that closes the popover. Place inside Popover.Popup.',\n});\n\nexport function PopoverRoot({ defaultOpen = false, modal = false, children }: PopoverRootProps) {\n  return (\n    <BasePopover.Root defaultOpen={defaultOpen} modal={modal}>\n      {children}\n    </BasePopover.Root>\n  );\n}\n\nexport function PopoverTrigger({\n  openOnHover = false,\n  delay = 300,\n  closeDelay,\n  className,\n  children,\n  ...props\n}: PopoverTriggerProps) {\n  return (\n    <BasePopover.Trigger\n      {...props}\n      openOnHover={openOnHover}\n      delay={delay}\n      closeDelay={closeDelay}\n      className={className}\n      data-fs-popover-trigger=\"\"\n    >\n      {children}\n    </BasePopover.Trigger>\n  );\n}\n\nexport function PopoverPortal({ children }: PopoverPortalProps) {\n  return <BasePopover.Portal>{children}</BasePopover.Portal>;\n}\n\nexport function PopoverBackdrop({ className, children, ...props }: PopoverBackdropProps) {\n  return (\n    <BasePopover.Backdrop {...props} className={className} data-fs-popover-backdrop=\"\">\n      {children}\n    </BasePopover.Backdrop>\n  );\n}\n\nexport function PopoverPositioner({\n  side = 'bottom',\n  align = 'center',\n  sideOffset = 0,\n  className,\n  children,\n  ...props\n}: PopoverPositionerProps) {\n  return (\n    <BasePopover.Positioner\n      {...props}\n      side={side}\n      align={align}\n      sideOffset={sideOffset}\n      className={className}\n      data-fs-popover-positioner=\"\"\n    >\n      {children}\n    </BasePopover.Positioner>\n  );\n}\n\nexport function PopoverPopup({ className, children, ...props }: PopoverPopupProps) {\n  return (\n    <BasePopover.Popup {...props} className={className} data-fs-popover-popup=\"\">\n      {children}\n    </BasePopover.Popup>\n  );\n}\n\nexport function PopoverArrow({ className, children, ...props }: PopoverArrowProps) {\n  return (\n    <BasePopover.Arrow {...props} className={className} data-fs-popover-arrow=\"\">\n      {children}\n    </BasePopover.Arrow>\n  );\n}\n\nexport function PopoverViewport({ className, children, ...props }: PopoverViewportProps) {\n  return (\n    <BasePopover.Viewport {...props} className={className} data-fs-popover-viewport=\"\">\n      {children}\n    </BasePopover.Viewport>\n  );\n}\n\nexport function PopoverTitle({ className, children, ...props }: PopoverTitleProps) {\n  return (\n    <BasePopover.Title {...props} className={className} data-fs-popover-title=\"\">\n      {children}\n    </BasePopover.Title>\n  );\n}\n\nexport function PopoverDescription({ className, children, ...props }: PopoverDescriptionProps) {\n  return (\n    <BasePopover.Description {...props} className={className} data-fs-popover-description=\"\">\n      {children}\n    </BasePopover.Description>\n  );\n}\n\nexport function PopoverClose({ className, children, ...props }: PopoverCloseProps) {\n  return (\n    <BasePopover.Close {...props} className={className} data-fs-popover-close=\"\">\n      {children}\n    </BasePopover.Close>\n  );\n}\n\nexport const Popover = {\n  Root: PopoverRoot,\n  Trigger: PopoverTrigger,\n  Portal: PopoverPortal,\n  Backdrop: PopoverBackdrop,\n  Positioner: PopoverPositioner,\n  Popup: PopoverPopup,\n  Arrow: PopoverArrow,\n  Viewport: PopoverViewport,\n  Title: PopoverTitle,\n  Description: PopoverDescription,\n  Close: PopoverClose,\n};\n"],"mappings":";;;;;;AA4CA,MAAa,wBAAwB,gBAAkC;CACrE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAgB,UAAU;CAAS;CACpD,QAAQ;EACN,aAAa;GAAE,MAAM;GAAW,SAAS;GAAO,OAAO;EAAe;EACtE,OAAO;GAAE,MAAM;GAAW,SAAS;GAAO,OAAO;EAAQ;CAC3D;CACA,WACE;AACJ,CAAC;AAED,MAAa,2BAA2B,gBAAqC;CAC3E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAmB,UAAU;CAAS;CACvD,QAAQ;EACN,aAAa;GAAE,MAAM;GAAW,SAAS;GAAO,OAAO;EAAgB;EACvE,OAAO;GAAE,MAAM;GAAU,SAAS;GAAK,OAAO;EAAQ;EACtD,YAAY;GAAE,MAAM;GAAU,SAAS;GAAG,OAAO;EAAc;CACjE;CACA,WAAW;AACb,CAAC;AAED,MAAa,0BAA0B,gBAAoC;CACzE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAkB,UAAU;CAAS;CACtD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,4BAA4B,gBAAsC;CAC7E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAoB,UAAU;CAAS;CACxD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,8BAA8B,gBAAwC;CACjF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAsB,UAAU;CAAS;CAC1D,QAAQ;EACN,MAAM;GAAE,MAAM;IAAC;IAAO;IAAU;IAAQ;GAAO;GAAY,SAAS;GAAU,OAAO;EAAO;EAC5F,OAAO;GAAE,MAAM;IAAC;IAAS;IAAU;GAAK;GAAY,SAAS;GAAU,OAAO;EAAQ;EACtF,YAAY;GAAE,MAAM;GAAU,SAAS;GAAG,OAAO;EAAc;CACjE;CACA,WAAW;AACb,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,4BAA4B,gBAAsC;CAC7E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAoB,UAAU;CAAS;CACxD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,+BAA+B,gBAAyC;CACnF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAuB,UAAU;CAAS;CAC3D,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,SAAgB,YAAY,EAAE,cAAc,OAAO,QAAQ,OAAO,YAA8B;CAC9F,OACE,oBAACA,QAAY,MAAb;EAA+B;EAAoB;EAChD;CACe,CAAA;AAEtB;AAEA,SAAgB,eAAe,EAC7B,cAAc,OACd,QAAQ,KACR,YACA,WACA,UACA,GAAG,SACmB;CACtB,OACE,oBAACA,QAAY,SAAb;EACE,GAAI;EACS;EACN;EACK;EACD;EACX,2BAAwB;EAEvB;CACkB,CAAA;AAEzB;AAEA,SAAgB,cAAc,EAAE,YAAgC;CAC9D,OAAO,oBAACA,QAAY,QAAb,EAAqB,SAA6B,CAAA;AAC3D;AAEA,SAAgB,gBAAgB,EAAE,WAAW,UAAU,GAAG,SAA+B;CACvF,OACE,oBAACA,QAAY,UAAb;EAAsB,GAAI;EAAkB;EAAW,4BAAyB;EAC7E;CACmB,CAAA;AAE1B;AAEA,SAAgB,kBAAkB,EAChC,OAAO,UACP,QAAQ,UACR,aAAa,GACb,WACA,UACA,GAAG,SACsB;CACzB,OACE,oBAACA,QAAY,YAAb;EACE,GAAI;EACE;EACC;EACK;EACD;EACX,8BAA2B;EAE1B;CACqB,CAAA;AAE5B;AAEA,SAAgB,aAAa,EAAE,WAAW,UAAU,GAAG,SAA4B;CACjF,OACE,oBAACA,QAAY,OAAb;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;EACvE;CACgB,CAAA;AAEvB;AAEA,SAAgB,aAAa,EAAE,WAAW,UAAU,GAAG,SAA4B;CACjF,OACE,oBAACA,QAAY,OAAb;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;EACvE;CACgB,CAAA;AAEvB;AAEA,SAAgB,gBAAgB,EAAE,WAAW,UAAU,GAAG,SAA+B;CACvF,OACE,oBAACA,QAAY,UAAb;EAAsB,GAAI;EAAkB;EAAW,4BAAyB;EAC7E;CACmB,CAAA;AAE1B;AAEA,SAAgB,aAAa,EAAE,WAAW,UAAU,GAAG,SAA4B;CACjF,OACE,oBAACA,QAAY,OAAb;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;EACvE;CACgB,CAAA;AAEvB;AAEA,SAAgB,mBAAmB,EAAE,WAAW,UAAU,GAAG,SAAkC;CAC7F,OACE,oBAACA,QAAY,aAAb;EAAyB,GAAI;EAAkB;EAAW,+BAA4B;EACnF;CACsB,CAAA;AAE7B;AAEA,SAAgB,aAAa,EAAE,WAAW,UAAU,GAAG,SAA4B;CACjF,OACE,oBAACA,QAAY,OAAb;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;EACvE;CACgB,CAAA;AAEvB;AAEA,MAAaC,YAAU;CACrB,MAAM;CACN,SAAS;CACT,QAAQ;CACR,UAAU;CACV,YAAY;CACZ,OAAO;CACP,OAAO;CACP,UAAU;CACV,OAAO;CACP,aAAa;CACb,OAAO;AACT"}

package/dist/particles/postal-code-field/postal-code-field.d.ts

@@ -0,0 +1,75 @@
+import { ContentValue } from "../../core/dist/define-content-type.js";
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef, FocusEvent } from "react";
+//#region src/particles/postal-code-field/postal-code-field.d.ts
+export declare const PostalCodeFieldContent: {
+  readonly id: "postal-code-field";
+  readonly title: "Postal Code Field";
+  readonly description: "Editorial copy for the postal-code input.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Label";
+      };
+      readonly placeholder: {
+        readonly type: "string";
+        readonly title: "Placeholder";
+      };
+      readonly errorMessage: {
+        readonly type: "string";
+        readonly title: "Error message";
+      };
+    };
+  };
+};
+export type PostalCodeFieldProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValue' | 'value' | 'onChange' | 'onBlur'> & {
+  /** Mask template: `9` digit, `A` alpha, `S` alphanumeric, `*` any, interleaved with literals.
+   *  Pipe-delimited alternates (`99999|99999-999`) cover formats of different lengths. */
+  mask?: string;
+  label?: string;
+  placeholder?: string;
+  errorMessage?: string;
+  /** Controlled value; masked on render, so a raw value is accepted. */
+  value?: string;
+  defaultValue?: string;
+  /** Called with the masked value on every change. */
+  onValueChange?: (value: string) => void;
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+  /** Host-forced invalid state (e.g. a server rejection); ORs with the internal blur verdict. */
+  invalid?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  name?: string;
+  /** Merchant-authored copy, sliced from the page/layout content entry; wins over the props when
+   *  present. Absent in a non-CMS store — the props are the fallback. The mask is not authored here:
+   *  it is a build-time schema prop. */
+  $content?: ContentValue<typeof PostalCodeFieldContent>;
+};
+/** Remove the mask's literal separators, leaving only slot characters. */
+export declare function stripPostalCodeMask(value: string, mask: string): string;
+/**
+ * Sanitize (digit-only masks), truncate to the mask's slot count, then apply the mask. Idempotent:
+ * stripping the literals first means an already-masked value and a raw one produce the same display.
+ */
+export declare function applyPostalCodeMask(rawValue: string, mask: string): string;
+/**
+ * True when the value fills every slot of the mask — of any mask in a pipe-delimited set, so a
+ * shorter alternate counts as complete. An empty value is NOT complete: emptiness is the host's
+ * submit-gating concern, not this field's.
+ */
+export declare function isPostalCodeComplete(value: string, mask: string): boolean;
+export declare const PostalCodeFieldDefinition: ComponentDefinition<PostalCodeFieldProps>;
+/**
+ * Presentational postal-code input (particle). Composes the `Field` and `Input` particles and owns
+ * one piece of logic: applying the configured mask template on every change, plus a blur verdict on
+ * whether the value fills the mask. It is country-agnostic — the pattern is configuration, not a
+ * country table — and data-agnostic: the value, the submit, and the server's verdict belong to the
+ * host, which surfaces a rejection through `invalid` + `errorMessage`.
+ */
+export declare function PostalCodeField({ mask, label, placeholder, errorMessage, value, defaultValue, onValueChange, onBlur, invalid, required, disabled, name, $content, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: PostalCodeFieldProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=postal-code-field.d.ts.map

package/dist/particles/postal-code-field/postal-code-field.js

@@ -0,0 +1,169 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import { defineContentType } from "../../core/dist/define-content-type.js";
+import "../../core/dist/index.js";
+import { Field } from "../field/field.js";
+import { Input } from "../input/input.js";
+import { applyMask, countSlots, isDigitOnly, isSlotToken } from "../shared/input-mask.js";
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/particles/postal-code-field/postal-code-field.tsx
+/** Brazilian CEP. */
+const DEFAULT_MASK = "99999-999";
+const PostalCodeFieldContent = defineContentType({
+	id: "postal-code-field",
+	title: "Postal Code Field",
+	description: "Editorial copy for the postal-code input.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			label: {
+				type: "string",
+				title: "Label"
+			},
+			placeholder: {
+				type: "string",
+				title: "Placeholder"
+			},
+			errorMessage: {
+				type: "string",
+				title: "Error message"
+			}
+		}
+	}
+});
+/** Slot count of the longest mask in a (possibly pipe-delimited) template. */
+function maxSlots(mask) {
+	return Math.max(...mask.split("|").map(countSlots));
+}
+/** Remove the mask's literal separators, leaving only slot characters. */
+function stripPostalCodeMask(value, mask) {
+	const literals = new Set([...mask].filter((char) => char !== "|" && !isSlotToken(char)));
+	return [...value].filter((char) => !literals.has(char)).join("");
+}
+/**
+* Sanitize (digit-only masks), truncate to the mask's slot count, then apply the mask. Idempotent:
+* stripping the literals first means an already-masked value and a raw one produce the same display.
+*/
+function applyPostalCodeMask(rawValue, mask) {
+	const slotChars = stripPostalCodeMask(rawValue, mask);
+	const sanitized = isDigitOnly(mask) ? slotChars.replaceAll(/\D/g, "") : slotChars;
+	return applyMask(sanitized.slice(0, maxSlots(mask)), mask);
+}
+/**
+* True when the value fills every slot of the mask — of any mask in a pipe-delimited set, so a
+* shorter alternate counts as complete. An empty value is NOT complete: emptiness is the host's
+* submit-gating concern, not this field's.
+*/
+function isPostalCodeComplete(value, mask) {
+	const slotChars = stripPostalCodeMask(value, mask);
+	if (!slotChars) return false;
+	return mask.split("|").some((single) => slotChars.length === countSlots(single));
+}
+const PostalCodeFieldDefinition = defineComponent({
+	name: "PostalCodeField",
+	importPath: "@vtex/faststore/components",
+	component: PostalCodeField,
+	content: PostalCodeFieldContent,
+	editor: {
+		label: "Postal Code Field",
+		category: "content"
+	},
+	schema: {
+		mask: {
+			type: "string",
+			default: DEFAULT_MASK,
+			label: "Mask pattern"
+		},
+		label: {
+			type: "string",
+			label: "Label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		},
+		errorMessage: {
+			type: "string",
+			label: "Error message"
+		},
+		required: {
+			type: "boolean",
+			default: false,
+			label: "Required"
+		},
+		disabled: {
+			type: "boolean",
+			default: false,
+			label: "Disabled"
+		}
+	},
+	guideline: "Presentational postal-code input composing the Field and Input particles; formats the value against the configured mask template as the shopper types and flags an incomplete value on blur. Data-agnostic (value/defaultValue/onValueChange) — a host such as the region modal owns submission and surfaces server errors through invalid/errorMessage. Set mask to the country format at build time (default 99999-999, BR CEP); the CMS edits only label, placeholder, and error copy."
+});
+/**
+* Presentational postal-code input (particle). Composes the `Field` and `Input` particles and owns
+* one piece of logic: applying the configured mask template on every change, plus a blur verdict on
+* whether the value fills the mask. It is country-agnostic — the pattern is configuration, not a
+* country table — and data-agnostic: the value, the submit, and the server's verdict belong to the
+* host, which surfaces a rejection through `invalid` + `errorMessage`.
+*/
+function PostalCodeField({ mask = DEFAULT_MASK, label, placeholder, errorMessage, value, defaultValue = "", onValueChange, onBlur, invalid = false, required = false, disabled = false, name = "postalCode", $content, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }) {
+	const isControlled = value !== void 0;
+	const [internalValue, setInternalValue] = useState(() => applyPostalCodeMask(defaultValue, mask));
+	const [blurInvalid, setBlurInvalid] = useState(false);
+	const displayValue = applyPostalCodeMask(isControlled ? value : internalValue, mask);
+	const showInvalid = invalid || blurInvalid;
+	const numericOnly = isDigitOnly(mask);
+	const resolvedLabel = $content?.label?.trim() ? $content.label : label;
+	const resolvedPlaceholder = $content?.placeholder?.trim() ? $content.placeholder : placeholder;
+	const resolvedError = $content?.errorMessage?.trim() ? $content.errorMessage : errorMessage;
+	function handleChange(event) {
+		const masked = applyPostalCodeMask(event.target.value, mask);
+		if (!isControlled) setInternalValue(masked);
+		if (blurInvalid) setBlurInvalid(false);
+		onValueChange?.(masked);
+	}
+	function handleBlur(event) {
+		setBlurInvalid(displayValue.trim() !== "" && !isPostalCodeComplete(displayValue, mask));
+		onBlur?.(event);
+	}
+	return /* @__PURE__ */ jsxs(Field.Root, {
+		...props,
+		className,
+		name,
+		invalid: showInvalid,
+		disabled,
+		"data-fs-postal-code-field": "",
+		children: [
+			resolvedLabel ? /* @__PURE__ */ jsx(Field.Label, {
+				"data-fs-postal-code-field-label": "",
+				children: resolvedLabel
+			}) : null,
+			/* @__PURE__ */ jsx(Input, {
+				"data-fs-postal-code-field-input": "",
+				type: "text",
+				name,
+				required,
+				disabled,
+				placeholder: resolvedPlaceholder,
+				"aria-label": ariaLabel,
+				"aria-labelledby": ariaLabelledBy,
+				autoComplete: "postal-code",
+				value: displayValue,
+				...numericOnly ? { inputMode: "numeric" } : {},
+				onChange: handleChange,
+				onBlur: handleBlur
+			}),
+			showInvalid && resolvedError ? /* @__PURE__ */ jsx(Field.Error, {
+				match: true,
+				"data-fs-postal-code-field-error": "",
+				children: resolvedError
+			}) : null
+		]
+	});
+}
+//#endregion
+export { PostalCodeField, PostalCodeFieldContent, PostalCodeFieldDefinition, applyPostalCodeMask, isPostalCodeComplete, stripPostalCodeMask };
+
+//# sourceMappingURL=postal-code-field.js.map

package/dist/particles/postal-code-field/postal-code-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postal-code-field.js","names":[],"sources":["../../../src/particles/postal-code-field/postal-code-field.tsx"],"sourcesContent":["'use client';\nimport { type ContentValue, defineComponent, defineContentType } from '@vtex/fs-core';\nimport type { ChangeEvent, ComponentPropsWithRef, FocusEvent } from 'react';\nimport { useState } from 'react';\nimport { Field } from '../field/field.js';\nimport { Input } from '../input/input.js';\nimport { applyMask, countSlots, isDigitOnly, isSlotToken } from '../shared/input-mask.js';\n\n/** Brazilian CEP. */\nconst DEFAULT_MASK = '99999-999';\n\nexport const PostalCodeFieldContent = defineContentType({\n  id: 'postal-code-field',\n  title: 'Postal Code Field',\n  description: 'Editorial copy for the postal-code input.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: { type: 'string', title: 'Label' },\n      placeholder: { type: 'string', title: 'Placeholder' },\n      errorMessage: { type: 'string', title: 'Error message' },\n    },\n  },\n});\n\nexport type PostalCodeFieldProps = Omit<\n  ComponentPropsWithRef<'div'>,\n  'defaultValue' | 'value' | 'onChange' | 'onBlur'\n> & {\n  /** Mask template: `9` digit, `A` alpha, `S` alphanumeric, `*` any, interleaved with literals.\n   *  Pipe-delimited alternates (`99999|99999-999`) cover formats of different lengths. */\n  mask?: string;\n  label?: string;\n  placeholder?: string;\n  errorMessage?: string;\n  /** Controlled value; masked on render, so a raw value is accepted. */\n  value?: string;\n  defaultValue?: string;\n  /** Called with the masked value on every change. */\n  onValueChange?: (value: string) => void;\n  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;\n  /** Host-forced invalid state (e.g. a server rejection); ORs with the internal blur verdict. */\n  invalid?: boolean;\n  required?: boolean;\n  disabled?: boolean;\n  name?: string;\n  /** Merchant-authored copy, sliced from the page/layout content entry; wins over the props when\n   *  present. Absent in a non-CMS store — the props are the fallback. The mask is not authored here:\n   *  it is a build-time schema prop. */\n  $content?: ContentValue<typeof PostalCodeFieldContent>;\n};\n\n/** Slot count of the longest mask in a (possibly pipe-delimited) template. */\nfunction maxSlots(mask: string): number {\n  return Math.max(...mask.split('|').map(countSlots));\n}\n\n/** Remove the mask's literal separators, leaving only slot characters. */\nexport function stripPostalCodeMask(value: string, mask: string): string {\n  const literals = new Set([...mask].filter((char) => char !== '|' && !isSlotToken(char)));\n  return [...value].filter((char) => !literals.has(char)).join('');\n}\n\n/**\n * Sanitize (digit-only masks), truncate to the mask's slot count, then apply the mask. Idempotent:\n * stripping the literals first means an already-masked value and a raw one produce the same display.\n */\nexport function applyPostalCodeMask(rawValue: string, mask: string): string {\n  const slotChars = stripPostalCodeMask(rawValue, mask);\n  const sanitized = isDigitOnly(mask) ? slotChars.replaceAll(/\\D/g, '') : slotChars;\n  return applyMask(sanitized.slice(0, maxSlots(mask)), mask);\n}\n\n/**\n * True when the value fills every slot of the mask — of any mask in a pipe-delimited set, so a\n * shorter alternate counts as complete. An empty value is NOT complete: emptiness is the host's\n * submit-gating concern, not this field's.\n */\nexport function isPostalCodeComplete(value: string, mask: string): boolean {\n  const slotChars = stripPostalCodeMask(value, mask);\n  if (!slotChars) return false;\n  return mask.split('|').some((single) => slotChars.length === countSlots(single));\n}\n\nexport const PostalCodeFieldDefinition = defineComponent<PostalCodeFieldProps>({\n  name: 'PostalCodeField',\n  importPath: '@vtex/faststore/components',\n  component: PostalCodeField,\n  content: PostalCodeFieldContent,\n  editor: { label: 'Postal Code Field', category: 'content' },\n  schema: {\n    mask: { type: 'string', default: DEFAULT_MASK, label: 'Mask pattern' },\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    errorMessage: { type: 'string', label: 'Error message' },\n    required: { type: 'boolean', default: false, label: 'Required' },\n    disabled: { type: 'boolean', default: false, label: 'Disabled' },\n  },\n  guideline:\n    'Presentational postal-code input composing the Field and Input particles; formats the value against the configured mask template as the shopper types and flags an incomplete value on blur. Data-agnostic (value/defaultValue/onValueChange) — a host such as the region modal owns submission and surfaces server errors through invalid/errorMessage. Set mask to the country format at build time (default 99999-999, BR CEP); the CMS edits only label, placeholder, and error copy.',\n});\n\n/**\n * Presentational postal-code input (particle). Composes the `Field` and `Input` particles and owns\n * one piece of logic: applying the configured mask template on every change, plus a blur verdict on\n * whether the value fills the mask. It is country-agnostic — the pattern is configuration, not a\n * country table — and data-agnostic: the value, the submit, and the server's verdict belong to the\n * host, which surfaces a rejection through `invalid` + `errorMessage`.\n */\nexport function PostalCodeField({\n  mask = DEFAULT_MASK,\n  label,\n  placeholder,\n  errorMessage,\n  value,\n  defaultValue = '',\n  onValueChange,\n  onBlur,\n  invalid = false,\n  required = false,\n  disabled = false,\n  name = 'postalCode',\n  $content,\n  className,\n  // Naming attributes belong on the control, not on the root the rest of the props land on. They are\n  // the only way to name the field when no label resolves.\n  'aria-label': ariaLabel,\n  'aria-labelledby': ariaLabelledBy,\n  ...props\n}: PostalCodeFieldProps) {\n  const isControlled = value !== undefined;\n  const [internalValue, setInternalValue] = useState(() => applyPostalCodeMask(defaultValue, mask));\n  const [blurInvalid, setBlurInvalid] = useState(false);\n\n  const currentValue = isControlled ? value : internalValue;\n  const displayValue = applyPostalCodeMask(currentValue, mask);\n  const showInvalid = invalid || blurInvalid;\n  const numericOnly = isDigitOnly(mask);\n\n  // Each content field falls back on its own, so a cleared one keeps the authored prop.\n  const resolvedLabel = $content?.label?.trim() ? $content.label : label;\n  const resolvedPlaceholder = $content?.placeholder?.trim() ? $content.placeholder : placeholder;\n  const resolvedError = $content?.errorMessage?.trim() ? $content.errorMessage : errorMessage;\n\n  function handleChange(event: ChangeEvent<HTMLInputElement>) {\n    const masked = applyPostalCodeMask(event.target.value, mask);\n    if (!isControlled) setInternalValue(masked);\n    // Clear a prior blur verdict while typing; it is re-evaluated on the next blur.\n    if (blurInvalid) setBlurInvalid(false);\n    onValueChange?.(masked);\n  }\n\n  function handleBlur(event: FocusEvent<HTMLInputElement>) {\n    // Judge the displayed value: a host can hand over a raw one carrying characters the mask drops,\n    // and a verdict on those would contradict what the shopper sees.\n    setBlurInvalid(displayValue.trim() !== '' && !isPostalCodeComplete(displayValue, mask));\n    onBlur?.(event);\n  }\n\n  return (\n    <Field.Root\n      {...props}\n      className={className}\n      name={name}\n      invalid={showInvalid}\n      disabled={disabled}\n      data-fs-postal-code-field=\"\"\n    >\n      {resolvedLabel ? <Field.Label data-fs-postal-code-field-label=\"\">{resolvedLabel}</Field.Label> : null}\n      {/* `Input` wires into `Field.Root` on its own — no `Field.Control` wrapper. */}\n      <Input\n        data-fs-postal-code-field-input=\"\"\n        type=\"text\"\n        name={name}\n        required={required}\n        disabled={disabled}\n        placeholder={resolvedPlaceholder}\n        aria-label={ariaLabel}\n        aria-labelledby={ariaLabelledBy}\n        autoComplete=\"postal-code\"\n        value={displayValue}\n        {...(numericOnly ? { inputMode: 'numeric' as const } : {})}\n        onChange={handleChange}\n        onBlur={handleBlur}\n      />\n      {showInvalid && resolvedError ? (\n        <Field.Error match data-fs-postal-code-field-error=\"\">\n          {resolvedError}\n        </Field.Error>\n      ) : null}\n    </Field.Root>\n  );\n}\n"],"mappings":"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"}

package/dist/particles/promotion/promotion.d.ts

@@ -0,0 +1,46 @@
+import { ContentValue } from "../../core/dist/define-content-type.js";
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/particles/promotion/promotion.d.ts
+export declare const PromotionContent: {
+  readonly id: "promotion";
+  readonly title: "Promotion";
+  readonly description: "Editorial fields for a promotional callout.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["title", "body"];
+    readonly properties: {
+      readonly title: {
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly title: "Title";
+      };
+      readonly body: {
+        readonly type: "string";
+        readonly title: "Body";
+      };
+      readonly image: {
+        readonly type: "string";
+        readonly format: "uri";
+        readonly title: "Image";
+        readonly widget: {
+          readonly 'ui:widget': "media-gallery";
+        };
+      };
+      readonly imageAlt: {
+        readonly type: "string";
+        readonly title: "Image alt text";
+      };
+    };
+  };
+};
+export type PromotionProps = ComponentPropsWithRef<'section'> & {
+  /** Injected by the compiler, sliced from the page's or layout's composite content entry. */
+  $content?: ContentValue<typeof PromotionContent>;
+};
+export declare const PromotionDefinition: ComponentDefinition<PromotionProps>;
+export declare function Promotion({ $content, className, ...props }: PromotionProps): import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+//# sourceMappingURL=promotion.d.ts.map

package/dist/particles/promotion/promotion.js

@@ -0,0 +1,78 @@
+import { defineComponent } from "../../core/dist/define-component.js";
+import { defineContentType } from "../../core/dist/define-content-type.js";
+import "../../core/dist/index.js";
+import { Image } from "../image/image.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/particles/promotion/promotion.tsx
+const PromotionContent = defineContentType({
+	id: "promotion",
+	title: "Promotion",
+	description: "Editorial fields for a promotional callout.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		required: ["title", "body"],
+		properties: {
+			title: {
+				type: "string",
+				minLength: 1,
+				title: "Title"
+			},
+			body: {
+				type: "string",
+				title: "Body"
+			},
+			image: {
+				type: "string",
+				format: "uri",
+				title: "Image",
+				widget: { "ui:widget": "media-gallery" }
+			},
+			imageAlt: {
+				type: "string",
+				title: "Image alt text"
+			}
+		}
+	}
+});
+const PromotionDefinition = defineComponent({
+	name: "Promotion",
+	importPath: "@vtex/faststore/components",
+	component: Promotion,
+	content: PromotionContent,
+	editor: {
+		label: "Promotion",
+		category: "content"
+	},
+	schema: {},
+	guideline: "Editorial promotional callout driven entirely by CMS content. See promotion.md."
+});
+function Promotion({ $content, className, ...props }) {
+	if (!$content) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		...props,
+		className,
+		"data-fs-promotion": "",
+		children: [
+			$content.image ? /* @__PURE__ */ jsx(Image, {
+				src: $content.image,
+				alt: $content.imageAlt ?? "",
+				"data-fs-promotion-image": ""
+			}) : null,
+			/* @__PURE__ */ jsx("h2", {
+				"data-fs-text": "",
+				"data-fs-text-variant": "heading",
+				"data-fs-promotion-title": "",
+				children: $content.title
+			}),
+			/* @__PURE__ */ jsx("p", {
+				"data-fs-promotion-body": "",
+				children: $content.body
+			})
+		]
+	});
+}
+//#endregion
+export { Promotion, PromotionContent, PromotionDefinition };
+
+//# sourceMappingURL=promotion.js.map

package/dist/particles/promotion/promotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion.js","names":[],"sources":["../../../src/particles/promotion/promotion.tsx"],"sourcesContent":["import { type ContentValue, defineComponent, defineContentType } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\nimport { Image } from '../image/image.js';\n\n// ---------------------------------------------------------------------------\n// Content model\n// ---------------------------------------------------------------------------\n\nexport const PromotionContent = defineContentType({\n  id: 'promotion',\n  title: 'Promotion',\n  description: 'Editorial fields for a promotional callout.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    required: ['title', 'body'],\n    properties: {\n      title: { type: 'string', minLength: 1, title: 'Title' },\n      body: { type: 'string', title: 'Body' },\n      image: { type: 'string', format: 'uri', title: 'Image', widget: { 'ui:widget': 'media-gallery' } },\n      imageAlt: { type: 'string', title: 'Image alt text' },\n    },\n  },\n});\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type PromotionProps = ComponentPropsWithRef<'section'> & {\n  /** Injected by the compiler, sliced from the page's or layout's composite content entry. */\n  $content?: ContentValue<typeof PromotionContent>;\n};\n\n// ---------------------------------------------------------------------------\n// Definition\n// ---------------------------------------------------------------------------\n\nexport const PromotionDefinition = defineComponent({\n  name: 'Promotion',\n  importPath: '@vtex/faststore/components',\n  component: Promotion,\n  content: PromotionContent,\n  editor: { label: 'Promotion', category: 'content' },\n  schema: {},\n  guideline: 'Editorial promotional callout driven entirely by CMS content. See promotion.md.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementation\n// ---------------------------------------------------------------------------\n\nexport function Promotion({ $content, className, ...props }: PromotionProps) {\n  if (!$content) return null;\n\n  return (\n    <section {...props} className={className} data-fs-promotion=\"\">\n      {$content.image ? <Image src={$content.image} alt={$content.imageAlt ?? ''} data-fs-promotion-image=\"\" /> : null}\n      <h2 data-fs-text=\"\" data-fs-text-variant=\"heading\" data-fs-promotion-title=\"\">\n        {$content.title}\n      </h2>\n      <p data-fs-promotion-body=\"\">{$content.body}</p>\n    </section>\n  );\n}\n"],"mappings":";;;;;;AAQA,MAAa,mBAAmB,kBAAkB;CAChD,IAAI;CACJ,OAAO;CACP,aAAa;CACb,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,UAAU,CAAC,SAAS,MAAM;EAC1B,YAAY;GACV,OAAO;IAAE,MAAM;IAAU,WAAW;IAAG,OAAO;GAAQ;GACtD,MAAM;IAAE,MAAM;IAAU,OAAO;GAAO;GACtC,OAAO;IAAE,MAAM;IAAU,QAAQ;IAAO,OAAO;IAAS,QAAQ,EAAE,aAAa,gBAAgB;GAAE;GACjG,UAAU;IAAE,MAAM;IAAU,OAAO;GAAiB;EACtD;CACF;AACF,CAAC;AAeD,MAAa,sBAAsB,gBAAgB;CACjD,MAAM;CACN,YAAY;CACZ,WAAW;CACX,SAAS;CACT,QAAQ;EAAE,OAAO;EAAa,UAAU;CAAU;CAClD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAMD,SAAgB,UAAU,EAAE,UAAU,WAAW,GAAG,SAAyB;CAC3E,IAAI,CAAC,UAAU,OAAO;CAEtB,OACE,qBAAC,WAAD;EAAS,GAAI;EAAkB;EAAW,qBAAkB;EAA5D,UAAA;GACG,SAAS,QAAQ,oBAAC,OAAD;IAAO,KAAK,SAAS;IAAO,KAAK,SAAS,YAAY;IAAI,2BAAwB;GAAI,CAAA,IAAI;GAC5G,oBAAC,MAAD;IAAI,gBAAa;IAAG,wBAAqB;IAAU,2BAAwB;IACxE,UAAA,SAAS;GACR,CAAA;GACJ,oBAAC,KAAD;IAAG,0BAAuB;IAAI,UAAA,SAAS;GAAQ,CAAA;EACxC;;AAEb"}

package/dist/particles/quantity-selector/quantity-selector.d.ts

@@ -0,0 +1,30 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/particles/quantity-selector/quantity-selector.d.ts
+export type QuantitySelectorRootProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValue' | 'value'> & {
+  value?: number | null;
+  defaultValue?: number;
+  onQuantityChange?: (quantity: number | null) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+};
+export type QuantitySelectorMessageProps = ComponentPropsWithRef<'div'>;
+/**
+ * Interim: the default copy lives in the component until the `@vtex/fs-i18n` operational-message
+ * catalog exists. Translations key off this stable id; a store overrides the copy via `children`.
+ */
+export declare const QUANTITY_MAX_EXCEEDED_MESSAGE_ID = "quantity-selector.max-exceeded";
+export declare function defaultMaxExceededMessage(max: number): string;
+export declare const QuantitySelectorRootDefinition: ComponentDefinition<QuantitySelectorRootProps>;
+export declare const QuantitySelectorMessageDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>;
+export declare function QuantitySelectorRoot({ value, defaultValue, onQuantityChange, min, max, step, disabled, className, children, ...props }: QuantitySelectorRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function QuantitySelectorMessage({ className, children, ...props }: QuantitySelectorMessageProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const QuantitySelector: {
+  Root: typeof QuantitySelectorRoot;
+  Message: typeof QuantitySelectorMessage;
+};
+//#endregion
+//# sourceMappingURL=quantity-selector.d.ts.map

package/dist/particles/quantity-selector/quantity-selector.js

@@ -0,0 +1,116 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { createContext, useContext, useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { NumberField } from "@base-ui/react/number-field";
+//#region src/particles/quantity-selector/quantity-selector.tsx
+const QuantitySelectorContext = createContext({ exceededMax: null });
+/**
+* Interim: the default copy lives in the component until the `@vtex/fs-i18n` operational-message
+* catalog exists. Translations key off this stable id; a store overrides the copy via `children`.
+*/
+const QUANTITY_MAX_EXCEEDED_MESSAGE_ID = "quantity-selector.max-exceeded";
+function defaultMaxExceededMessage(max) {
+	return `Only ${max} available. Quantity adjusted to ${max}.`;
+}
+const QuantitySelectorRootDefinition = defineComponent({
+	name: "QuantitySelectorRoot",
+	importPath: "@vtex/faststore/components",
+	component: QuantitySelectorRoot,
+	editor: {
+		label: "Quantity Selector",
+		category: "form"
+	},
+	schema: {
+		defaultValue: {
+			type: "number",
+			default: 1,
+			label: "Default Quantity"
+		},
+		min: {
+			type: "number",
+			default: 1,
+			label: "Min Quantity"
+		},
+		max: {
+			type: "number",
+			label: "Max Quantity"
+		},
+		step: {
+			type: "number",
+			default: 1,
+			label: "Step"
+		},
+		disabled: {
+			type: "boolean",
+			default: false,
+			label: "Disabled"
+		}
+	},
+	guideline: "Generic quantity selector. Wraps NumberField and manages value state. Compose as: QuantitySelectorRoot > NumberFieldGroup > NumberFieldDecrement + NumberFieldInput + NumberFieldIncrement. Add QuantitySelectorMessage to surface the max-exceeded message. On a PDP, bind `max` to product stock via $data."
+});
+const QuantitySelectorMessageDefinition = defineComponent({
+	name: "QuantitySelectorMessage",
+	importPath: "@vtex/faststore/components",
+	component: QuantitySelectorMessage,
+	editor: {
+		label: "Quantity Selector Message",
+		category: "form"
+	},
+	schema: {},
+	guideline: "Message shown when a shopper enters a quantity above `max` and it was clamped down; renders nothing otherwise. Must be a descendant of QuantitySelectorRoot. Set `children` to override the default copy."
+});
+function QuantitySelectorRoot({ value, defaultValue = 1, onQuantityChange, min = 1, max, step = 1, disabled, className, children, ...props }) {
+	const [exceededAt, setExceededAt] = useState(null);
+	const [maxJudgedAgainst, setMaxJudgedAgainst] = useState(max);
+	if (max !== maxJudgedAgainst) {
+		setMaxJudgedAgainst(max);
+		setExceededAt(null);
+	}
+	function handleValueChange(newValue) {
+		onQuantityChange?.(newValue);
+	}
+	function handleValueCommitted(committed) {
+		setExceededAt(max != null && committed != null && committed > max ? max : null);
+	}
+	const exceededMax = exceededAt != null && exceededAt === max ? exceededAt : null;
+	const context = useMemo(() => ({ exceededMax }), [exceededMax]);
+	return /* @__PURE__ */ jsx(NumberField.Root, {
+		...props,
+		value,
+		defaultValue: value === void 0 ? defaultValue : void 0,
+		onValueChange: handleValueChange,
+		onValueCommitted: handleValueCommitted,
+		min,
+		max,
+		step,
+		disabled,
+		className,
+		"data-fs-quantity-selector": "",
+		children: /* @__PURE__ */ jsx(QuantitySelectorContext, {
+			value: context,
+			children
+		})
+	});
+}
+function QuantitySelectorMessage({ className, children, ...props }) {
+	const { exceededMax } = useContext(QuantitySelectorContext);
+	if (exceededMax == null) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		role: "status",
+		"aria-live": "polite",
+		className,
+		"data-fs-quantity-selector-message": "",
+		children: children ?? defaultMaxExceededMessage(exceededMax)
+	});
+}
+const QuantitySelector = {
+	Root: QuantitySelectorRoot,
+	Message: QuantitySelectorMessage
+};
+//#endregion
+export { QUANTITY_MAX_EXCEEDED_MESSAGE_ID, QuantitySelector, QuantitySelectorMessage, QuantitySelectorMessageDefinition, QuantitySelectorRoot, QuantitySelectorRootDefinition, defaultMaxExceededMessage };
+
+//# sourceMappingURL=quantity-selector.js.map

package/dist/particles/quantity-selector/quantity-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quantity-selector.js","names":["BaseNumberField"],"sources":["../../../src/particles/quantity-selector/quantity-selector.tsx"],"sourcesContent":["'use client';\nimport { NumberField as BaseNumberField } from '@base-ui/react/number-field';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\nimport { createContext, useContext, useMemo, useState } from 'react';\n\nexport type QuantitySelectorRootProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValue' | 'value'> & {\n  value?: number | null;\n  defaultValue?: number;\n  onQuantityChange?: (quantity: number | null) => void;\n  min?: number;\n  max?: number;\n  step?: number;\n  disabled?: boolean;\n};\n\nexport type QuantitySelectorMessageProps = ComponentPropsWithRef<'div'>;\n\ntype QuantitySelectorContextValue = {\n  /** The maximum an entry was clamped down to, or null when the last entry was within range. */\n  exceededMax: number | null;\n};\n\n// Seeded with a safe default so QuantitySelectorMessage never throws when rendered\n// outside a QuantitySelectorRoot (it simply renders nothing).\nconst QuantitySelectorContext = createContext<QuantitySelectorContextValue>({ exceededMax: null });\n\n/**\n * Interim: the default copy lives in the component until the `@vtex/fs-i18n` operational-message\n * catalog exists. Translations key off this stable id; a store overrides the copy via `children`.\n */\nexport const QUANTITY_MAX_EXCEEDED_MESSAGE_ID = 'quantity-selector.max-exceeded';\n\nexport function defaultMaxExceededMessage(max: number): string {\n  return `Only ${max} available. Quantity adjusted to ${max}.`;\n}\n\nexport const QuantitySelectorRootDefinition = defineComponent<QuantitySelectorRootProps>({\n  name: 'QuantitySelectorRoot',\n  importPath: '@vtex/faststore/components',\n  component: QuantitySelectorRoot,\n  editor: { label: 'Quantity Selector', category: 'form' },\n  schema: {\n    defaultValue: { type: 'number', default: 1, label: 'Default Quantity' },\n    min: { type: 'number', default: 1, label: 'Min Quantity' },\n    max: { type: 'number', label: 'Max Quantity' },\n    step: { type: 'number', default: 1, label: 'Step' },\n    disabled: { type: 'boolean', default: false, label: 'Disabled' },\n  },\n  guideline:\n    'Generic quantity selector. Wraps NumberField and manages value state. Compose as: QuantitySelectorRoot > NumberFieldGroup > NumberFieldDecrement + NumberFieldInput + NumberFieldIncrement. Add QuantitySelectorMessage to surface the max-exceeded message. On a PDP, bind `max` to product stock via $data.',\n});\n\nexport const QuantitySelectorMessageDefinition = defineComponent<QuantitySelectorMessageProps>({\n  name: 'QuantitySelectorMessage',\n  importPath: '@vtex/faststore/components',\n  component: QuantitySelectorMessage,\n  editor: { label: 'Quantity Selector Message', category: 'form' },\n  schema: {},\n  guideline:\n    'Message shown when a shopper enters a quantity above `max` and it was clamped down; renders nothing otherwise. Must be a descendant of QuantitySelectorRoot. Set `children` to override the default copy.',\n});\n\nexport function QuantitySelectorRoot({\n  value,\n  defaultValue = 1,\n  onQuantityChange,\n  min = 1,\n  max,\n  step = 1,\n  disabled,\n  className,\n  children,\n  ...props\n}: QuantitySelectorRootProps) {\n  // The `max` an entry was clamped down to, kept so a later `max` change can invalidate it.\n  const [exceededAt, setExceededAt] = useState<number | null>(null);\n\n  // A recorded exceed belongs to the `max` it was judged against. When `max` changes — a PDP\n  // variant switch lands new stock — that record is stale, so we clear it synchronously during\n  // render (React's recommended alternative to a useEffect for resetting state on a prop change).\n  // Without this a 5 → 10 → 5 run of `max` values would resurrect a message the shopper never\n  // triggered on the return to 5.\n  const [maxJudgedAgainst, setMaxJudgedAgainst] = useState(max);\n  if (max !== maxJudgedAgainst) {\n    setMaxJudgedAgainst(max);\n    setExceededAt(null);\n  }\n\n  function handleValueChange(newValue: number | null) {\n    onQuantityChange?.(newValue);\n  }\n\n  // Base UI still clamps the committed value to `max` (via onValueChange above), but reports the\n  // raw entered value here on commit. A committed value above `max` means the entry was reduced,\n  // which is what the message explains. Every other commit path is already within range and clears it.\n  function handleValueCommitted(committed: number | null) {\n    setExceededAt(max != null && committed != null && committed > max ? max : null);\n  }\n\n  // `exceededAt` is now always relative to the current `max` (the render-time reset above clears it\n  // on any change), but the `=== max` guard is kept as a cheap invariant assertion.\n  const exceededMax = exceededAt != null && exceededAt === max ? exceededAt : null;\n  const context = useMemo<QuantitySelectorContextValue>(() => ({ exceededMax }), [exceededMax]);\n\n  return (\n    <BaseNumberField.Root\n      {...props}\n      value={value}\n      defaultValue={value === undefined ? defaultValue : undefined}\n      onValueChange={handleValueChange}\n      onValueCommitted={handleValueCommitted}\n      min={min}\n      max={max}\n      step={step}\n      disabled={disabled}\n      className={className}\n      data-fs-quantity-selector=\"\"\n    >\n      <QuantitySelectorContext value={context}>{children}</QuantitySelectorContext>\n    </BaseNumberField.Root>\n  );\n}\n\nexport function QuantitySelectorMessage({ className, children, ...props }: QuantitySelectorMessageProps) {\n  const { exceededMax } = useContext(QuantitySelectorContext);\n  if (exceededMax == null) return null;\n\n  return (\n    <div {...props} role=\"status\" aria-live=\"polite\" className={className} data-fs-quantity-selector-message=\"\">\n      {children ?? defaultMaxExceededMessage(exceededMax)}\n    </div>\n  );\n}\n\nexport const QuantitySelector = {\n  Root: QuantitySelectorRoot,\n  Message: QuantitySelectorMessage,\n};\n"],"mappings":";;;;;;;AAyBA,MAAM,0BAA0B,cAA4C,EAAE,aAAa,KAAK,CAAC;;;;;AAMjG,MAAa,mCAAmC;AAEhD,SAAgB,0BAA0B,KAAqB;CAC7D,OAAO,QAAQ,IAAI,mCAAmC,IAAI;AAC5D;AAEA,MAAa,iCAAiC,gBAA2C;CACvF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAqB,UAAU;CAAO;CACvD,QAAQ;EACN,cAAc;GAAE,MAAM;GAAU,SAAS;GAAG,OAAO;EAAmB;EACtE,KAAK;GAAE,MAAM;GAAU,SAAS;GAAG,OAAO;EAAe;EACzD,KAAK;GAAE,MAAM;GAAU,OAAO;EAAe;EAC7C,MAAM;GAAE,MAAM;GAAU,SAAS;GAAG,OAAO;EAAO;EAClD,UAAU;GAAE,MAAM;GAAW,SAAS;GAAO,OAAO;EAAW;CACjE;CACA,WACE;AACJ,CAAC;AAED,MAAa,oCAAoC,gBAA8C;CAC7F,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAA6B,UAAU;CAAO;CAC/D,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,SAAgB,qBAAqB,EACnC,OACA,eAAe,GACf,kBACA,MAAM,GACN,KACA,OAAO,GACP,UACA,WACA,UACA,GAAG,SACyB;CAE5B,MAAM,CAAC,YAAY,iBAAiB,SAAwB,IAAI;CAOhE,MAAM,CAAC,kBAAkB,uBAAuB,SAAS,GAAG;CAC5D,IAAI,QAAQ,kBAAkB;EAC5B,oBAAoB,GAAG;EACvB,cAAc,IAAI;CACpB;CAEA,SAAS,kBAAkB,UAAyB;EAClD,mBAAmB,QAAQ;CAC7B;CAKA,SAAS,qBAAqB,WAA0B;EACtD,cAAc,OAAO,QAAQ,aAAa,QAAQ,YAAY,MAAM,MAAM,IAAI;CAChF;CAIA,MAAM,cAAc,cAAc,QAAQ,eAAe,MAAM,aAAa;CAC5E,MAAM,UAAU,eAA6C,EAAE,YAAY,IAAI,CAAC,WAAW,CAAC;CAE5F,OACE,oBAACA,YAAgB,MAAjB;EACE,GAAI;EACG;EACP,cAAc,UAAU,KAAA,IAAY,eAAe,KAAA;EACnD,eAAe;EACf,kBAAkB;EACb;EACA;EACC;EACI;EACC;EACX,6BAA0B;EAE1B,UAAA,oBAAC,yBAAD;GAAyB,OAAO;GAAU;EAAkC,CAAA;CACxD,CAAA;AAE1B;AAEA,SAAgB,wBAAwB,EAAE,WAAW,UAAU,GAAG,SAAuC;CACvG,MAAM,EAAE,gBAAgB,WAAW,uBAAuB;CAC1D,IAAI,eAAe,MAAM,OAAO;CAEhC,OACE,oBAAC,OAAD;EAAK,GAAI;EAAO,MAAK;EAAS,aAAU;EAAoB;EAAW,qCAAkC;EACtG,UAAA,YAAY,0BAA0B,WAAW;CAC/C,CAAA;AAET;AAEA,MAAa,mBAAmB;CAC9B,MAAM;CACN,SAAS;AACX"}

package/dist/particles/radio/radio.d.ts

@@ -0,0 +1,36 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/particles/radio/radio.d.ts
+export type RadioGroupProps = Omit<ComponentPropsWithRef<'div'>, 'defaultValue'> & {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  name?: string;
+};
+export type RadioRootProps = {
+  value: string;
+  disabled?: boolean;
+  id?: string;
+  className?: string;
+  children?: ReactNode;
+};
+export type RadioIndicatorProps = ComponentPropsWithRef<'span'> & {
+  keepMounted?: boolean;
+};
+export declare const RadioGroupDefinition: ComponentDefinition<RadioGroupProps>;
+export declare const RadioRootDefinition: ComponentDefinition<RadioRootProps>;
+export declare const RadioIndicatorDefinition: ComponentDefinition<RadioIndicatorProps>;
+export declare function RadioGroup({ className, children, ...props }: RadioGroupProps): import("react/jsx-runtime").JSX.Element;
+export declare function RadioRoot({ value, disabled, id, className, children }: RadioRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function RadioIndicator({ keepMounted, className, children, ...props }: RadioIndicatorProps): import("react/jsx-runtime").JSX.Element;
+export declare const Radio: {
+  Group: typeof RadioGroup;
+  Root: typeof RadioRoot;
+  Indicator: typeof RadioIndicator;
+};
+//#endregion
+//# sourceMappingURL=radio.d.ts.map