@vtex/faststore 0.0.1

package/dist/particles/address-summary/address-summary.js

@@ -0,0 +1,129 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { createContext, useContext } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/particles/address-summary/address-summary.tsx
+const AddressSummaryContext = createContext(null);
+function useAddressSummary() {
+	const ctx = useContext(AddressSummaryContext);
+	if (!ctx) throw new Error("AddressSummary must be used inside AddressSummaryRoot.");
+	return ctx;
+}
+const AddressSummaryRootDefinition = defineComponent({
+	name: "AddressSummaryRoot",
+	importPath: "@vtex/faststore/components",
+	component: AddressSummaryRoot,
+	providesContext: "address-summary",
+	editor: {
+		label: "Address Summary Root",
+		category: "content"
+	},
+	schema: {},
+	guideline: "Provides a postal address to descendant presentational components via context (no business coupling). Compose a matter component that owns address data as the source of the address prop, and AddressSummary (or a future alternative presentation reading the same context) as the child that renders it."
+});
+const AddressSummaryDefinition = defineComponent({
+	name: "AddressSummary",
+	importPath: "@vtex/faststore/components",
+	component: AddressSummary,
+	requiresContext: "address-summary",
+	editor: {
+		label: "Address Summary",
+		category: "content"
+	},
+	schema: {},
+	guideline: "The address block: recipient, street line, locality line, in that order by default. Compose AddressSummaryRecipient / Street / Locality as children to choose the order or drop a line; the wrapper, and any styling on it, is the same either way. Must be a descendant of AddressSummaryRoot."
+});
+const AddressSummaryRecipientDefinition = defineComponent({
+	name: "AddressSummaryRecipient",
+	importPath: "@vtex/faststore/components",
+	component: AddressSummaryRecipient,
+	requiresContext: "address-summary",
+	editor: {
+		label: "Address Summary Recipient",
+		category: "content"
+	},
+	schema: {},
+	guideline: "Who the delivery is addressed to, or nothing when the address carries no recipient. Place it in whatever order the summary should read. Must be a descendant of AddressSummaryRoot."
+});
+const AddressSummaryStreetDefinition = defineComponent({
+	name: "AddressSummaryStreet",
+	importPath: "@vtex/faststore/components",
+	component: AddressSummaryStreet,
+	requiresContext: "address-summary",
+	editor: {
+		label: "Address Summary Street",
+		category: "content"
+	},
+	schema: {},
+	guideline: "Street, number and complement on one line, or nothing when all three are absent. Must be a descendant of AddressSummaryRoot."
+});
+const AddressSummaryLocalityDefinition = defineComponent({
+	name: "AddressSummaryLocality",
+	importPath: "@vtex/faststore/components",
+	component: AddressSummaryLocality,
+	requiresContext: "address-summary",
+	editor: {
+		label: "Address Summary Locality",
+		category: "content"
+	},
+	schema: {},
+	guideline: "Neighborhood, city, state and postal code on one line, or nothing when all are absent. Must be a descendant of AddressSummaryRoot."
+});
+function AddressSummaryRoot({ address, children }) {
+	return /* @__PURE__ */ jsx(AddressSummaryContext.Provider, {
+		value: address,
+		children
+	});
+}
+function AddressSummary({ className, children }) {
+	return /* @__PURE__ */ jsx("div", {
+		className,
+		"data-fs-address-summary": "",
+		children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+			/* @__PURE__ */ jsx(AddressSummaryRecipient, {}),
+			/* @__PURE__ */ jsx(AddressSummaryStreet, {}),
+			/* @__PURE__ */ jsx(AddressSummaryLocality, {})
+		] })
+	});
+}
+/** Who the delivery is addressed to. Renders nothing when the address carries no recipient. */
+function AddressSummaryRecipient({ className }) {
+	const { recipientName } = useAddressSummary();
+	if (!recipientName) return null;
+	return /* @__PURE__ */ jsx("p", {
+		className,
+		"data-fs-address-summary-recipient": "",
+		children: recipientName
+	});
+}
+/** Street, number and complement on one line. Renders nothing when all three are absent. */
+function AddressSummaryStreet({ className }) {
+	const { street, number, complement } = useAddressSummary();
+	const line = [[street, number].filter(Boolean).join(", "), complement].filter(Boolean).join(" - ");
+	if (!line) return null;
+	return /* @__PURE__ */ jsx("p", {
+		className,
+		"data-fs-address-summary-address": "",
+		children: line
+	});
+}
+/** Neighborhood, city, state and postal code on one line. Renders nothing when all are absent. */
+function AddressSummaryLocality({ className }) {
+	const { neighborhood, city, state, postalCode } = useAddressSummary();
+	const line = [
+		neighborhood,
+		[city, state].filter(Boolean).join(" - "),
+		postalCode
+	].filter(Boolean).join(", ");
+	if (!line) return null;
+	return /* @__PURE__ */ jsx("p", {
+		className,
+		"data-fs-address-summary-locality": "",
+		children: line
+	});
+}
+//#endregion
+export { AddressSummary, AddressSummaryDefinition, AddressSummaryLocality, AddressSummaryLocalityDefinition, AddressSummaryRecipient, AddressSummaryRecipientDefinition, AddressSummaryRoot, AddressSummaryRootDefinition, AddressSummaryStreet, AddressSummaryStreetDefinition, useAddressSummary };
+
+//# sourceMappingURL=address-summary.js.map

package/dist/particles/address-summary/address-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-summary.js","names":[],"sources":["../../../src/particles/address-summary/address-summary.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useContext } from 'react';\n\n/**\n * AddressSummary particle (no business coupling — ADR-0001): a presentational display for a\n * postal address, driven entirely by AddressSummaryRoot's context rather than props. Any matter\n * component that owns address data (e.g. ShippingAddressSelectedSummary, ShippingAddressSavedOption)\n * provides it via AddressSummaryRoot; AddressSummary reads and renders it. A future alternative\n * presentation (e.g. a \"LeanAddressSummary\") would read the same context and could be composed in\n * its place — swapping the presentation is a composition change, not a new data-binding.\n */\n\nexport type AddressSummaryFields = Readonly<{\n  recipientName?: string | null;\n  street?: string | null;\n  number?: string | null;\n  complement?: string | null;\n  neighborhood?: string | null;\n  city?: string | null;\n  state?: string | null;\n  postalCode?: string | null;\n}>;\n\nconst AddressSummaryContext = createContext<AddressSummaryFields | null>(null);\n\nexport function useAddressSummary(): AddressSummaryFields {\n  const ctx = useContext(AddressSummaryContext);\n  if (!ctx) throw new Error('AddressSummary must be used inside AddressSummaryRoot.');\n  return ctx;\n}\n\nexport type AddressSummaryRootProps = {\n  /** The address fields provided to descendant presentational components via context. */\n  address: AddressSummaryFields;\n  children?: ReactNode;\n};\n\nexport type AddressSummaryProps = {\n  className?: string;\n  /** The lines to render, in order. Defaults to recipient, street, locality when omitted. */\n  children?: ReactNode;\n};\n\nexport type AddressSummaryLineProps = {\n  className?: string;\n};\n\nexport const AddressSummaryRootDefinition = defineComponent<AddressSummaryRootProps>({\n  name: 'AddressSummaryRoot',\n  importPath: '@vtex/faststore/components',\n  component: AddressSummaryRoot,\n  providesContext: 'address-summary',\n  editor: { label: 'Address Summary Root', category: 'content' },\n  schema: {},\n  guideline:\n    'Provides a postal address to descendant presentational components via context (no business coupling). Compose a matter component that owns address data as the source of the address prop, and AddressSummary (or a future alternative presentation reading the same context) as the child that renders it.',\n});\n\nexport const AddressSummaryDefinition = defineComponent<AddressSummaryProps>({\n  name: 'AddressSummary',\n  importPath: '@vtex/faststore/components',\n  component: AddressSummary,\n  requiresContext: 'address-summary',\n  editor: { label: 'Address Summary', category: 'content' },\n  schema: {},\n  guideline:\n    'The address block: recipient, street line, locality line, in that order by default. Compose AddressSummaryRecipient / Street / Locality as children to choose the order or drop a line; the wrapper, and any styling on it, is the same either way. Must be a descendant of AddressSummaryRoot.',\n});\n\nexport const AddressSummaryRecipientDefinition = defineComponent<AddressSummaryLineProps>({\n  name: 'AddressSummaryRecipient',\n  importPath: '@vtex/faststore/components',\n  component: AddressSummaryRecipient,\n  requiresContext: 'address-summary',\n  editor: { label: 'Address Summary Recipient', category: 'content' },\n  schema: {},\n  guideline:\n    'Who the delivery is addressed to, or nothing when the address carries no recipient. Place it in whatever order the summary should read. Must be a descendant of AddressSummaryRoot.',\n});\n\nexport const AddressSummaryStreetDefinition = defineComponent<AddressSummaryLineProps>({\n  name: 'AddressSummaryStreet',\n  importPath: '@vtex/faststore/components',\n  component: AddressSummaryStreet,\n  requiresContext: 'address-summary',\n  editor: { label: 'Address Summary Street', category: 'content' },\n  schema: {},\n  guideline:\n    'Street, number and complement on one line, or nothing when all three are absent. Must be a descendant of AddressSummaryRoot.',\n});\n\nexport const AddressSummaryLocalityDefinition = defineComponent<AddressSummaryLineProps>({\n  name: 'AddressSummaryLocality',\n  importPath: '@vtex/faststore/components',\n  component: AddressSummaryLocality,\n  requiresContext: 'address-summary',\n  editor: { label: 'Address Summary Locality', category: 'content' },\n  schema: {},\n  guideline:\n    'Neighborhood, city, state and postal code on one line, or nothing when all are absent. Must be a descendant of AddressSummaryRoot.',\n});\n\nexport function AddressSummaryRoot({ address, children }: AddressSummaryRootProps) {\n  return <AddressSummaryContext.Provider value={address}>{children}</AddressSummaryContext.Provider>;\n}\n\nexport function AddressSummary({ className, children }: AddressSummaryProps) {\n  return (\n    <div className={className} data-fs-address-summary=\"\">\n      {children ?? (\n        <>\n          <AddressSummaryRecipient />\n          <AddressSummaryStreet />\n          <AddressSummaryLocality />\n        </>\n      )}\n    </div>\n  );\n}\n\n/** Who the delivery is addressed to. Renders nothing when the address carries no recipient. */\nexport function AddressSummaryRecipient({ className }: AddressSummaryLineProps) {\n  const { recipientName } = useAddressSummary();\n  if (!recipientName) return null;\n  return (\n    <p className={className} data-fs-address-summary-recipient=\"\">\n      {recipientName}\n    </p>\n  );\n}\n\n/** Street, number and complement on one line. Renders nothing when all three are absent. */\nexport function AddressSummaryStreet({ className }: AddressSummaryLineProps) {\n  const { street, number, complement } = useAddressSummary();\n  const line = [[street, number].filter(Boolean).join(', '), complement].filter(Boolean).join(' - ');\n  if (!line) return null;\n  return (\n    <p className={className} data-fs-address-summary-address=\"\">\n      {line}\n    </p>\n  );\n}\n\n/** Neighborhood, city, state and postal code on one line. Renders nothing when all are absent. */\nexport function AddressSummaryLocality({ className }: AddressSummaryLineProps) {\n  const { neighborhood, city, state, postalCode } = useAddressSummary();\n  const line = [neighborhood, [city, state].filter(Boolean).join(' - '), postalCode].filter(Boolean).join(', ');\n  if (!line) return null;\n  return (\n    <p className={className} data-fs-address-summary-locality=\"\">\n      {line}\n    </p>\n  );\n}\n"],"mappings":";;;;;;AAyBA,MAAM,wBAAwB,cAA2C,IAAI;AAE7E,SAAgB,oBAA0C;CACxD,MAAM,MAAM,WAAW,qBAAqB;CAC5C,IAAI,CAAC,KAAK,MAAM,IAAI,MAAM,wDAAwD;CAClF,OAAO;AACT;AAkBA,MAAa,+BAA+B,gBAAyC;CACnF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAwB,UAAU;CAAU;CAC7D,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,2BAA2B,gBAAqC;CAC3E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAmB,UAAU;CAAU;CACxD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,oCAAoC,gBAAyC;CACxF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAA6B,UAAU;CAAU;CAClE,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,iCAAiC,gBAAyC;CACrF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAA0B,UAAU;CAAU;CAC/D,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,mCAAmC,gBAAyC;CACvF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAA4B,UAAU;CAAU;CACjE,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,SAAgB,mBAAmB,EAAE,SAAS,YAAqC;CACjF,OAAO,oBAAC,sBAAsB,UAAvB;EAAgC,OAAO;EAAU;CAAyC,CAAA;AACnG;AAEA,SAAgB,eAAe,EAAE,WAAW,YAAiC;CAC3E,OACE,oBAAC,OAAD;EAAgB;EAAW,2BAAwB;EAChD,UAAA,YACC,qBAAA,UAAA,EAAA,UAAA;GACE,oBAAC,yBAAD,CAA0B,CAAA;GAC1B,oBAAC,sBAAD,CAAuB,CAAA;GACvB,oBAAC,wBAAD,CAAyB,CAAA;EACzB,EAAA,CAAA;CAED,CAAA;AAET;;AAGA,SAAgB,wBAAwB,EAAE,aAAsC;CAC9E,MAAM,EAAE,kBAAkB,kBAAkB;CAC5C,IAAI,CAAC,eAAe,OAAO;CAC3B,OACE,oBAAC,KAAD;EAAc;EAAW,qCAAkC;EACxD,UAAA;CACA,CAAA;AAEP;;AAGA,SAAgB,qBAAqB,EAAE,aAAsC;CAC3E,MAAM,EAAE,QAAQ,QAAQ,eAAe,kBAAkB;CACzD,MAAM,OAAO,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,KAAK;CACjG,IAAI,CAAC,MAAM,OAAO;CAClB,OACE,oBAAC,KAAD;EAAc;EAAW,mCAAgC;EACtD,UAAA;CACA,CAAA;AAEP;;AAGA,SAAgB,uBAAuB,EAAE,aAAsC;CAC7E,MAAM,EAAE,cAAc,MAAM,OAAO,eAAe,kBAAkB;CACpE,MAAM,OAAO;EAAC;EAAc,CAAC,MAAM,KAAK,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,KAAK;EAAG;CAAU,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,IAAI;CAC5G,IAAI,CAAC,MAAM,OAAO;CAClB,OACE,oBAAC,KAAD;EAAc;EAAW,oCAAiC;EACvD,UAAA;CACA,CAAA;AAEP"}

package/dist/particles/badge/badge.d.ts

@@ -0,0 +1,10 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/particles/badge/badge.d.ts
+/** Props for {@link Badge}. Extends all native `<span>` attributes. */
+export type BadgeProps = ComponentPropsWithRef<'span'>;
+export declare const BadgeDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>;
+export declare function Badge({ className, children, ...props }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=badge.d.ts.map

package/dist/particles/badge/badge.js

@@ -0,0 +1,27 @@
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/particles/badge/badge.tsx
+const BadgeDefinition = defineComponent({
+	name: "Badge",
+	importPath: "@vtex/faststore/components",
+	component: Badge,
+	editor: {
+		label: "Badge",
+		category: "content"
+	},
+	schema: {},
+	guideline: "Status, count, or category labels with semantic color variants. Use for tags, status indicators, and notification badges."
+});
+function Badge({ className, children, ...props }) {
+	return /* @__PURE__ */ jsx("span", {
+		...props,
+		className,
+		"data-fs-badge": "",
+		children
+	});
+}
+//#endregion
+export { Badge, BadgeDefinition };
+
+//# sourceMappingURL=badge.js.map

package/dist/particles/badge/badge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.js","names":[],"sources":["../../../src/particles/badge/badge.tsx"],"sourcesContent":["import { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\n\n/** Props for {@link Badge}. Extends all native `<span>` attributes. */\nexport type BadgeProps = ComponentPropsWithRef<'span'>;\n\nexport const BadgeDefinition = defineComponent<BadgeProps>({\n  name: 'Badge',\n  importPath: '@vtex/faststore/components',\n  component: Badge,\n  editor: { label: 'Badge', category: 'content' },\n  schema: {},\n  guideline:\n    'Status, count, or category labels with semantic color variants. Use for tags, status indicators, and notification badges.',\n});\n\nexport function Badge({ className, children, ...props }: BadgeProps) {\n  return (\n    <span {...props} className={className} data-fs-badge=\"\">\n      {children}\n    </span>\n  );\n}\n"],"mappings":";;;;AAMA,MAAa,kBAAkB,gBAA4B;CACzD,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAS,UAAU;CAAU;CAC9C,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,SAAgB,MAAM,EAAE,WAAW,UAAU,GAAG,SAAqB;CACnE,OACE,oBAAC,QAAD;EAAM,GAAI;EAAkB;EAAW,iBAAc;EAClD;CACG,CAAA;AAEV"}

package/dist/particles/button/button.d.ts

@@ -0,0 +1,18 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/particles/button/button.d.ts
+/** Props for {@link Button}. Extends all native `<button>` attributes. */
+export type ButtonProps = ComponentPropsWithRef<'button'>;
+/**
+ * General-purpose button built on Base UI's `<Button>`.
+ *
+ * @example
+ * ```tsx
+ * <Button>Click me</Button>
+ * ```
+ */
+export declare const ButtonDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>>;
+export declare function Button({ className, children, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=button.d.ts.map

package/dist/particles/button/button.js

@@ -0,0 +1,37 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { jsx } from "react/jsx-runtime";
+import { Button } from "@base-ui/react/button";
+//#region src/particles/button/button.tsx
+/**
+* General-purpose button built on Base UI's `<Button>`.
+*
+* @example
+* ```tsx
+* <Button>Click me</Button>
+* ```
+*/
+const ButtonDefinition = defineComponent({
+	name: "Button",
+	importPath: "@vtex/faststore/components",
+	component: Button$1,
+	editor: {
+		label: "Button",
+		category: "action"
+	},
+	schema: {},
+	guideline: "Composable action button — combine with Icon for icon buttons, Spinner for loading states. Ghost appearance can be achieved via className."
+});
+function Button$1({ className, children, ...props }) {
+	return /* @__PURE__ */ jsx(Button, {
+		...props,
+		className,
+		"data-fs-button": "",
+		children
+	});
+}
+//#endregion
+export { Button$1 as Button, ButtonDefinition };
+
+//# sourceMappingURL=button.js.map

package/dist/particles/button/button.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.js","names":["Button","BaseButton"],"sources":["../../../src/particles/button/button.tsx"],"sourcesContent":["'use client';\nimport { Button as BaseButton } from '@base-ui/react/button';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\n\n/** Props for {@link Button}. Extends all native `<button>` attributes. */\nexport type ButtonProps = ComponentPropsWithRef<'button'>;\n\n/**\n * General-purpose button built on Base UI's `<Button>`.\n *\n * @example\n * ```tsx\n * <Button>Click me</Button>\n * ```\n */\nexport const ButtonDefinition = defineComponent<ButtonProps>({\n  name: 'Button',\n  importPath: '@vtex/faststore/components',\n  component: Button,\n  editor: { label: 'Button', category: 'action' },\n  schema: {},\n  guideline:\n    'Composable action button — combine with Icon for icon buttons, Spinner for loading states. Ghost appearance can be achieved via className.',\n});\n\nexport function Button({ className, children, ...props }: ButtonProps) {\n  return (\n    <BaseButton {...props} className={className} data-fs-button=\"\">\n      {children}\n    </BaseButton>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AAgBA,MAAa,mBAAmB,gBAA6B;CAC3D,MAAM;CACN,YAAY;CACZ,WAAWA;CACX,QAAQ;EAAE,OAAO;EAAU,UAAU;CAAS;CAC9C,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,SAAgBA,SAAO,EAAE,WAAW,UAAU,GAAG,SAAsB;CACrE,OACE,oBAACC,QAAD;EAAY,GAAI;EAAkB;EAAW,kBAAe;EACzD;CACS,CAAA;AAEhB"}

package/dist/particles/carousel/carousel.d.ts

@@ -0,0 +1,60 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/particles/carousel/carousel.d.ts
+export type CarouselVariant = 'slide' | 'scroll';
+export type CarouselContextValue = {
+  currentPage: number;
+  itemCount: number;
+  itemsPerPage: number;
+  totalPages: number;
+  variant: CarouselVariant;
+  infiniteMode: boolean;
+  goToPage: (page: number) => void;
+  next: () => void;
+  previous: () => void;
+  canGoNext: boolean;
+  canGoPrevious: boolean;
+  setItemCount: (count: number) => void;
+};
+export type CarouselRootProps = ComponentPropsWithRef<'section'> & {
+  infiniteMode?: boolean;
+  variant?: CarouselVariant;
+  itemsPerPage?: number;
+  defaultPage?: number;
+  label?: string;
+};
+export type CarouselTrackProps = ComponentPropsWithRef<'div'> & {
+  children?: ReactNode;
+};
+export type CarouselPreviousProps = ComponentPropsWithRef<'button'> & {
+  children?: ReactNode;
+};
+export type CarouselNextProps = ComponentPropsWithRef<'button'> & {
+  children?: ReactNode;
+};
+export type CarouselBulletsProps = ComponentPropsWithRef<'div'> & {
+  ariaLabel?: string;
+  bulletLabel?: string;
+  hideWhenSingle?: boolean;
+};
+export declare function useCarousel(): CarouselContextValue;
+export declare function CarouselRoot({ infiniteMode, variant, itemsPerPage, defaultPage, label, children, ...props }: CarouselRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function CarouselTrack({ children, style, ref, onScroll, ...props }: CarouselTrackProps): import("react/jsx-runtime").JSX.Element;
+export declare function CarouselPrevious({ children, onClick, ...props }: CarouselPreviousProps): import("react/jsx-runtime").JSX.Element;
+export declare function CarouselNext({ children, onClick, ...props }: CarouselNextProps): import("react/jsx-runtime").JSX.Element;
+export declare function CarouselBullets({ ariaLabel, bulletLabel, hideWhenSingle, ...props }: CarouselBulletsProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const CarouselRootDefinition: ComponentDefinition<CarouselRootProps>;
+export declare const CarouselTrackDefinition: ComponentDefinition<CarouselTrackProps>;
+export declare const CarouselPreviousDefinition: ComponentDefinition<CarouselPreviousProps>;
+export declare const CarouselNextDefinition: ComponentDefinition<CarouselNextProps>;
+export declare const CarouselBulletsDefinition: ComponentDefinition<CarouselBulletsProps>;
+export declare const Carousel: {
+  Root: typeof CarouselRoot;
+  Track: typeof CarouselTrack;
+  Previous: typeof CarouselPrevious;
+  Next: typeof CarouselNext;
+  Bullets: typeof CarouselBullets;
+};
+//#endregion
+//# sourceMappingURL=carousel.d.ts.map

package/dist/particles/carousel/carousel.js

@@ -0,0 +1,335 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { Children, createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/particles/carousel/carousel.tsx
+const CarouselContext = createContext(null);
+function useCarousel() {
+	const ctx = useContext(CarouselContext);
+	if (!ctx) throw new Error("Carousel components must be used inside CarouselRoot.");
+	return ctx;
+}
+function CarouselRoot({ infiniteMode = false, variant = "slide", itemsPerPage = 1, defaultPage = 0, label = "Carousel", children, ...props }) {
+	const [currentPage, setCurrentPage] = useState(defaultPage);
+	const [itemCount, setItemCountState] = useState(0);
+	const perPage = Math.max(1, itemsPerPage);
+	const totalPages = Math.max(1, Math.ceil(itemCount / perPage));
+	const setItemCount = useCallback((count) => {
+		setItemCountState((prev) => prev === count ? prev : count);
+	}, []);
+	useEffect(() => {
+		if (itemCount === 0) return;
+		setCurrentPage((page) => Math.min(page, totalPages - 1));
+	}, [itemCount, totalPages]);
+	const goToPage = useCallback((page) => {
+		setCurrentPage(Math.max(0, Math.min(page, totalPages - 1)));
+	}, [totalPages]);
+	const next = useCallback(() => {
+		setCurrentPage((page) => infiniteMode ? (page + 1) % totalPages : Math.min(page + 1, totalPages - 1));
+	}, [infiniteMode, totalPages]);
+	const previous = useCallback(() => {
+		setCurrentPage((page) => infiniteMode ? (page - 1 + totalPages) % totalPages : Math.max(page - 1, 0));
+	}, [infiniteMode, totalPages]);
+	const canGoNext = infiniteMode ? totalPages > 1 : currentPage < totalPages - 1;
+	const canGoPrevious = infiniteMode ? totalPages > 1 : currentPage > 0;
+	const ctx = useMemo(() => ({
+		currentPage,
+		itemCount,
+		itemsPerPage: perPage,
+		totalPages,
+		variant,
+		infiniteMode,
+		goToPage,
+		next,
+		previous,
+		canGoNext,
+		canGoPrevious,
+		setItemCount
+	}), [
+		currentPage,
+		itemCount,
+		perPage,
+		totalPages,
+		variant,
+		infiniteMode,
+		goToPage,
+		next,
+		previous,
+		canGoNext,
+		canGoPrevious,
+		setItemCount
+	]);
+	return /* @__PURE__ */ jsx(CarouselContext, {
+		value: ctx,
+		children: /* @__PURE__ */ jsx("section", {
+			...props,
+			"data-fs-carousel": "",
+			"data-fs-carousel-variant": variant,
+			"aria-roledescription": "carousel",
+			"aria-label": label,
+			children
+		})
+	});
+}
+function CarouselTrack({ children, style, ref, onScroll, ...props }) {
+	const { setItemCount, itemsPerPage, currentPage, variant, goToPage } = useCarousel();
+	const items = Children.toArray(children);
+	const count = items.length;
+	const scrollRef = useRef(null);
+	const programmaticScroll = useRef(false);
+	const mergedScrollRef = useCallback((node) => {
+		scrollRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	}, [ref]);
+	useEffect(() => {
+		setItemCount(count);
+	}, [count, setItemCount]);
+	useEffect(() => {
+		if (variant !== "scroll") return;
+		const el = scrollRef.current;
+		if (!el || typeof el.scrollTo !== "function") return;
+		if (el.clientWidth > 0 && Math.round(el.scrollLeft / el.clientWidth) === currentPage) return;
+		programmaticScroll.current = true;
+		el.scrollTo({
+			left: currentPage * el.clientWidth,
+			behavior: "smooth"
+		});
+	}, [variant, currentPage]);
+	function handleScroll(event) {
+		onScroll?.(event);
+		const { clientWidth, scrollLeft } = event.currentTarget;
+		if (clientWidth <= 0) return;
+		const page = Math.round(scrollLeft / clientWidth);
+		if (programmaticScroll.current) {
+			if (page === currentPage) programmaticScroll.current = false;
+			return;
+		}
+		if (page !== currentPage) goToPage(page);
+	}
+	const itemStyle = {
+		flex: `0 0 ${100 / itemsPerPage}%`,
+		boxSizing: "border-box"
+	};
+	const renderedItems = items.map((child, index) => /* @__PURE__ */ jsx("div", {
+		"data-fs-carousel-item": "",
+		style: variant === "scroll" ? {
+			...itemStyle,
+			scrollSnapAlign: "start"
+		} : itemStyle,
+		children: child
+	}, index));
+	if (variant === "scroll") return /* @__PURE__ */ jsx("div", {
+		...props,
+		ref: mergedScrollRef,
+		onScroll: handleScroll,
+		"data-fs-carousel-track": "",
+		style: {
+			display: "flex",
+			overflowX: "auto",
+			scrollSnapType: "x mandatory",
+			...style
+		},
+		children: renderedItems
+	});
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		ref,
+		"data-fs-carousel-track": "",
+		style: {
+			overflow: "hidden",
+			...style
+		},
+		children: /* @__PURE__ */ jsx("div", {
+			"data-fs-carousel-viewport": "",
+			style: {
+				display: "flex",
+				transform: `translateX(-${currentPage * 100}%)`,
+				transition: "transform 300ms ease"
+			},
+			children: renderedItems
+		})
+	});
+}
+function CarouselPrevious({ children, onClick, ...props }) {
+	const { previous, canGoPrevious } = useCarousel();
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		disabled: !canGoPrevious,
+		onClick: (event) => {
+			onClick?.(event);
+			if (!event.defaultPrevented) previous();
+		},
+		"aria-label": "Previous",
+		"data-fs-carousel-previous": "",
+		...props,
+		children
+	});
+}
+function CarouselNext({ children, onClick, ...props }) {
+	const { next, canGoNext } = useCarousel();
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		disabled: !canGoNext,
+		onClick: (event) => {
+			onClick?.(event);
+			if (!event.defaultPrevented) next();
+		},
+		"aria-label": "Next",
+		"data-fs-carousel-next": "",
+		...props,
+		children
+	});
+}
+function CarouselBullets({ ariaLabel = "Choose page", bulletLabel = "Go to page {page}", hideWhenSingle = true, ...props }) {
+	const { totalPages, currentPage, goToPage } = useCarousel();
+	if (hideWhenSingle && totalPages <= 1) return null;
+	function handleKeyDown(event, page) {
+		let target = page;
+		switch (event.key) {
+			case "ArrowRight":
+				target = Math.min(page + 1, totalPages - 1);
+				break;
+			case "ArrowLeft":
+				target = Math.max(page - 1, 0);
+				break;
+			case "Home":
+				target = 0;
+				break;
+			case "End":
+				target = totalPages - 1;
+				break;
+			default: return;
+		}
+		event.preventDefault();
+		goToPage(target);
+		(event.currentTarget.parentElement?.querySelectorAll("[data-fs-carousel-bullet]"))?.[target]?.focus();
+	}
+	return /* @__PURE__ */ jsx("div", {
+		role: "group",
+		"aria-label": ariaLabel,
+		"data-fs-carousel-bullets": "",
+		...props,
+		children: Array.from({ length: totalPages }, (_, page) => {
+			const isActive = page === currentPage;
+			return /* @__PURE__ */ jsx("button", {
+				type: "button",
+				"aria-label": bulletLabel.replace("{page}", String(page + 1)),
+				"aria-current": isActive,
+				"data-fs-carousel-bullet": "",
+				"data-fs-carousel-bullet-selected": String(isActive),
+				onClick: () => goToPage(page),
+				onKeyDown: (event) => handleKeyDown(event, page)
+			}, page);
+		})
+	});
+}
+const CarouselRootDefinition = defineComponent({
+	name: "CarouselRoot",
+	importPath: "@vtex/faststore/components",
+	component: CarouselRoot,
+	editor: {
+		label: "Carousel Root",
+		category: "layout"
+	},
+	schema: {
+		infiniteMode: {
+			type: "boolean",
+			default: false,
+			label: "Infinite Mode"
+		},
+		variant: {
+			type: ["slide", "scroll"],
+			default: "slide",
+			label: "Variant"
+		},
+		itemsPerPage: {
+			type: "number",
+			default: 1,
+			label: "Items Per Page"
+		},
+		defaultPage: {
+			type: "number",
+			default: 0,
+			label: "Default Page"
+		},
+		label: {
+			type: "string",
+			default: "Carousel",
+			label: "Aria Label"
+		}
+	},
+	guideline: "Root of the carousel. Provides paging state to all parts. Compose as: CarouselRoot > (CarouselTrack > [item children] + CarouselPrevious + CarouselNext + CarouselBullets). Set infiniteMode=true to loop seamlessly (arrows never disable); variant=\"scroll\" for native overflow, \"slide\" for transform transitions. itemsPerPage sets how many children are visible per page. Holds no product or media data — nest any children in CarouselTrack."
+});
+const CarouselTrackDefinition = defineComponent({
+	name: "CarouselTrack",
+	importPath: "@vtex/faststore/components",
+	component: CarouselTrack,
+	editor: {
+		label: "Carousel Track",
+		category: "layout"
+	},
+	schema: {},
+	guideline: "Lays out the carousel items as a single track and reports the child count to CarouselRoot. Wraps each child in an item slot sized to 100/itemsPerPage percent. In slide variant it translates by page; in scroll variant it is the native scroll-snap container. Place the iterated children (e.g. product cards) directly inside. Must be inside CarouselRoot."
+});
+const CarouselPreviousDefinition = defineComponent({
+	name: "CarouselPrevious",
+	importPath: "@vtex/faststore/components",
+	component: CarouselPrevious,
+	editor: {
+		label: "Carousel Previous",
+		category: "action"
+	},
+	schema: {},
+	guideline: "Moves the track one page backward. Disabled on the first page when infiniteMode is off; never disabled when infiniteMode is on (wraps to the last page). Accepts any children (Icon, text). Must be inside CarouselRoot."
+});
+const CarouselNextDefinition = defineComponent({
+	name: "CarouselNext",
+	importPath: "@vtex/faststore/components",
+	component: CarouselNext,
+	editor: {
+		label: "Carousel Next",
+		category: "action"
+	},
+	schema: {},
+	guideline: "Moves the track one page forward. Disabled on the last page when infiniteMode is off; never disabled when infiniteMode is on (wraps to the first page). Accepts any children (Icon, text). Must be inside CarouselRoot."
+});
+const CarouselBulletsDefinition = defineComponent({
+	name: "CarouselBullets",
+	importPath: "@vtex/faststore/components",
+	component: CarouselBullets,
+	editor: {
+		label: "Carousel Bullets",
+		category: "action"
+	},
+	schema: {
+		ariaLabel: {
+			type: "string",
+			default: "Choose page",
+			label: "Aria Label"
+		},
+		bulletLabel: {
+			type: "string",
+			default: "Go to page {page}",
+			label: "Bullet Label Template"
+		},
+		hideWhenSingle: {
+			type: "boolean",
+			default: true,
+			label: "Hide when single page"
+		}
+	},
+	guideline: "Renders one bullet button per page and marks the active page. Supports ArrowLeft/ArrowRight/Home/End keyboard navigation. Returns null when there is a single page unless hideWhenSingle={false}. Use {page} in bulletLabel for the 1-based page number. Must be inside CarouselRoot."
+});
+const Carousel = {
+	Root: CarouselRoot,
+	Track: CarouselTrack,
+	Previous: CarouselPrevious,
+	Next: CarouselNext,
+	Bullets: CarouselBullets
+};
+//#endregion
+export { Carousel, CarouselBullets, CarouselBulletsDefinition, CarouselNext, CarouselNextDefinition, CarouselPrevious, CarouselPreviousDefinition, CarouselRoot, CarouselRootDefinition, CarouselTrack, CarouselTrackDefinition, useCarousel };
+
+//# sourceMappingURL=carousel.js.map