@asteby/storefront-react 0.2.0 → 0.4.0

package/dist/mockups.d.ts

@@ -0,0 +1,262 @@
+import * as react from 'react';
+import { SVGProps, ReactNode, CSSProperties, ComponentType } from 'react';
+import { Product, ProductVariant, Image } from '@asteby/storefront';
+import { BuiltinMockupData, MockupProduct, MockupVariant, GenericMockupData, PartMockupData, SupplementMockupData, TireMockupData, MockupKind } from '@asteby/storefront/mockup';
+export { BUILTIN_MOCKUP_KINDS, BuiltinMockupData, BuiltinMockupKind, DEFAULT_MOCKUP_KIND_RULES, GenericMockupData, MOCKUP_KIND_ATTRIBUTES, MOCKUP_TEXT_LIMITS, MockupDataMap, MockupKind, MockupKindRule, MockupProduct, MockupVariant, PartMockupData, ResolveMockupKindOptions, SupplementMockupData, SupplementShape, TireMockupData, cleanMockupText, genericMockupData, mockupDataFromProduct, mockupMonogram, partMockupData, resolveMockupKind, supplementMockupData, tireMockupData } from '@asteby/storefront/mockup';
+import { b as ImageProps } from './components-B5XhSH-m.js';
+
+/** Side of the square viewBox every mockup draws in. */
+declare const MOCKUP_SIZE = 400;
+/**
+ * Theme tokens. Each mockup reads `--mockup-*` (set them in the store CSS),
+ * falls back to the store theme (`--color-muted`, `--color-primary`... as
+ * emitted by `ThemeStyle`) and finally to neutral greys that follow
+ * `color-scheme` through `light-dark()`. No brand colors live here.
+ */
+declare const MOCKUP_TOKENS: {
+    readonly bg: "var(--mockup-bg, var(--color-muted, light-dark(#f4f4f5, #27272a)))";
+    readonly surface: "var(--mockup-surface, light-dark(#3f3f46, #0a0a0a))";
+    readonly 'surface-ink': "var(--mockup-surface-ink, light-dark(#e4e4e7, #a1a1aa))";
+    readonly label: "var(--mockup-label, var(--color-background, light-dark(#ffffff, #18181b)))";
+    readonly 'label-ink': "var(--mockup-label-ink, var(--color-foreground, light-dark(#18181b, #fafafa)))";
+    readonly ink: "var(--mockup-ink, var(--color-foreground, light-dark(#18181b, #fafafa)))";
+    readonly muted: "var(--mockup-muted, var(--color-muted-foreground, light-dark(#71717a, #a1a1aa)))";
+    readonly accent: "var(--mockup-accent, var(--color-primary, light-dark(#52525b, #d4d4d8)))";
+    readonly 'accent-ink': "var(--mockup-accent-ink, var(--color-primary-foreground, light-dark(#ffffff, #18181b)))";
+};
+type MockupTone = keyof typeof MOCKUP_TOKENS;
+/** `style` that paints an element with a token: `<rect style={tone('accent')} />`. */
+declare function tone(t: MockupTone, prop?: 'fill' | 'stroke'): CSSProperties;
+/** Monospace stack for part numbers and sizes (`--mockup-font-mono`). */
+declare const MOCKUP_MONO = "var(--mockup-font-mono, var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace))";
+/**
+ * Greedy word wrap by characters; the last allowed line ends in `…` when text
+ * is cut. Words longer than `wordMax` (default `maxChars`) are cut with `…`; a
+ * word between `maxChars` and `wordMax` keeps a line of its own, so the caller
+ * can shrink the font to fit it (`fitMockupFontSize`) instead of cutting it.
+ */
+declare function wrapMockupText(text: string | null | undefined, maxChars: number, maxLines: number, wordMax?: number): string[];
+/** Longest word (in characters) that still fits `width` at font size `min` (glyph width `ratio` em). */
+declare function mockupWordMax(width: number, min: number, ratio?: number): number;
+/** Font size so the longest line fits `width` (approximate glyph width `ratio` em). */
+declare function fitMockupFontSize(lines: readonly string[], width: number, max: number, min?: number, ratio?: number): number;
+type MockupTextProps = Omit<SVGProps<SVGTextElement>, 'children'> & {
+    lines: readonly string[];
+    x: number;
+    y: number;
+    size: number;
+    lineHeight?: number;
+    tone?: MockupTone;
+    weight?: number;
+    anchor?: 'start' | 'middle' | 'end';
+    mono?: boolean;
+};
+/** Multi-line `<text>`; `y` is the baseline of the first line. */
+declare function MockupText({ lines, x, y, size, lineHeight, tone: t, weight, anchor, mono, style, ...rest }: MockupTextProps): react.JSX.Element | null;
+type MockupFrameProps = Omit<SVGProps<SVGSVGElement>, 'children' | 'role' | 'ref'> & {
+    /** Accessible name (`aria-label` and `<title>`). */
+    label: string;
+    /** Hide from assistive tech (the product name is already next to it). */
+    decorative?: boolean;
+    /** Written to `data-mockup` for styling and tests. */
+    kind?: string;
+    children?: ReactNode;
+};
+/**
+ * The `<svg>` shell shared by every mockup: square viewBox, token variables,
+ * background, `role="img"` with an accessible name that says it is an
+ * illustration. Use it in custom renderers to get the same contract.
+ */
+declare function MockupFrame({ label, decorative, kind, children, style, width, height, ...rest }: MockupFrameProps): react.JSX.Element;
+
+/** Interface words used by the built-in mockups (generic UI text, not store copy). */
+type MockupLabels = {
+    /** Prefix of every accessible name, so a mockup is never announced as a photo. */
+    illustration: string;
+    size: string;
+    partNumber: string;
+    oem: string;
+    fits: string;
+    flavor: string;
+    /** Unit after a numeric `servings` attribute. */
+    servings: string;
+    lightTruck: string;
+    runFlat: string;
+};
+declare const DEFAULT_MOCKUP_LABELS: MockupLabels;
+/** Accessible name for built-in data: "Ilustración de referencia: <title>, <key spec>". */
+declare function describeMockup(data: Partial<BuiltinMockupData> & {
+    title?: string | null;
+}, labels?: MockupLabels): string;
+
+/** Props every mockup component receives. Spread the rest on `<MockupFrame>`. */
+type MockupComponentProps<D = unknown> = Omit<MockupFrameProps, 'label' | 'kind' | 'children'> & {
+    data: D;
+    /** Accessible name already built (prefixed with `labels.illustration`). */
+    label: string;
+    labels: MockupLabels;
+};
+type MockupComponent<D = unknown> = ComponentType<MockupComponentProps<D>>;
+/** A registered mockup: how to draw it and, optionally, how to read its data from a product. */
+type MockupRenderer<D = any> = {
+    component: MockupComponent<D>;
+    /** Product → data. Default: the built-in extractor for the kind (generic data for custom kinds). */
+    fromProduct?: (product: MockupProduct, variant?: MockupVariant | null) => D;
+    /** Data → accessible name. Default: `describeMockup`. */
+    describe?: (data: D, labels: MockupLabels) => string;
+};
+
+/** Closed box with the product monogram, the brand on the box and the name below. */
+declare function GenericMockup({ data, label, labels: _labels, ...rest }: MockupComponentProps<GenericMockupData>): react.JSX.Element;
+
+/** Hang tag ("ficha") with the part number in a band, the name and the compatibility. */
+declare function PartMockup({ data, label, labels, ...rest }: MockupComponentProps<PartMockupData>): react.JSX.Element;
+
+/** Tub, bottle or bag with a label: brand, product name, flavor and presentation. */
+declare function SupplementMockup({ data, label, labels, ...rest }: MockupComponentProps<SupplementMockupData>): react.JSX.Element;
+
+/** Tire seen from the side (tread blocks on the edge) with the size in big digits. Shows only what the data has. */
+declare function TireMockup({ data, label, labels, ...rest }: MockupComponentProps<TireMockupData>): react.JSX.Element;
+
+/** A renderer, or just its component (data then comes from the built-in extractor). */
+type MockupRendererInput<D = any> = MockupRenderer<D> | MockupComponent<D>;
+/** A resolved renderer: every hook filled in. */
+type ResolvedMockupRenderer<D = any> = Required<MockupRenderer<D>>;
+type MockupRegistry = {
+    /** Adds or replaces a kind. Returns the registry (chainable). */
+    register<D>(kind: MockupKind, renderer: MockupRendererInput<D>): MockupRegistry;
+    get(kind: MockupKind): ResolvedMockupRenderer | undefined;
+    has(kind: MockupKind): boolean;
+    kinds(): MockupKind[];
+    /** New registry with these entries plus the overrides (the original is untouched). */
+    extend(overrides?: Partial<Record<MockupKind, MockupRendererInput>>): MockupRegistry;
+};
+/** A registry of mockup kinds. Pass `BUILTIN_MOCKUPS` (or a subset) to start from the base ones. */
+declare function createMockupRegistry(initial?: Partial<Record<MockupKind, MockupRendererInput>>): MockupRegistry;
+/** The four base mockups. */
+declare const BUILTIN_MOCKUPS: {
+    tire: typeof TireMockup;
+    part: typeof PartMockup;
+    supplement: typeof SupplementMockup;
+    generic: typeof GenericMockup;
+};
+/** Registry used when no `MockupProvider`/`registry` prop is given. */
+declare const defaultMockupRegistry: MockupRegistry;
+/**
+ * Registers a kind in the default registry (call it once at module scope, e.g.
+ * in `app/root.tsx`). For an isolated registry use `createMockupRegistry` + `MockupProvider`.
+ */
+declare function registerMockup<D>(kind: MockupKind, renderer: MockupRendererInput<D>): MockupRegistry;
+/**
+ * Store-level kind resolver. Receives the default guess; return a kind to
+ * override it, or `null`/`undefined` to keep the default.
+ */
+type ResolveMockupKind = (product: MockupProduct, defaultKind: MockupKind) => MockupKind | null | undefined;
+type MockupConfig = {
+    registry: MockupRegistry;
+    resolveKind?: ResolveMockupKind | undefined;
+    labels: MockupLabels;
+};
+type MockupProviderProps = {
+    registry?: MockupRegistry;
+    resolveKind?: ResolveMockupKind;
+    labels?: Partial<MockupLabels>;
+    children?: ReactNode;
+};
+/** Per-store mockup configuration (registry, kind resolver, labels) for every `ProductImage` below. */
+declare function MockupProvider({ registry, resolveKind, labels, children }: MockupProviderProps): react.JSX.Element;
+/** Current mockup configuration (defaults when there is no provider). */
+declare function useMockupConfig(): MockupConfig;
+
+type SvgPassThrough = Omit<MockupFrameProps, 'label' | 'kind' | 'children'>;
+type ProductMockupProps<D = unknown> = SvgPassThrough & {
+    kind: MockupKind;
+    data: D;
+    /** Accessible name override (still prefixed with `labels.illustration`). */
+    label?: string;
+    labels?: Partial<MockupLabels>;
+    registry?: MockupRegistry;
+};
+/**
+ * Draws the mockup registered for `kind` with already extracted `data`
+ * (e.g. from `mockupDataFromProduct`). Unknown kinds fall back to `generic`;
+ * returns `null` when the registry has neither.
+ */
+declare function ProductMockup<D>({ kind, data, label, labels: labelOverrides, registry: registryProp, ...svg }: ProductMockupProps<D>): react.JSX.Element | null;
+/** Product fields `ProductImage` reads: the mockup fields plus the images. */
+type ProductImageProduct = MockupProduct & Partial<Pick<Product, 'featured_image' | 'images'>>;
+type ProductImageProps = Omit<ImageProps, 'data'> & {
+    product: ProductImageProduct;
+    /** Selected variant: its image wins; its options (flavor, presentation) feed the mockup. */
+    variant?: (MockupVariant & Partial<Pick<ProductVariant, 'image'>>) | null;
+    /** Explicit image (e.g. a gallery slide). `null` forces the mockup. */
+    image?: Image | null;
+    /** Forces a mockup kind (skips resolution). */
+    kind?: MockupKind;
+    resolveKind?: ResolveMockupKind;
+    registry?: MockupRegistry;
+    labels?: Partial<MockupLabels>;
+};
+/**
+ * The product's image from OPS (responsive `Image`: `alt`, intrinsic size,
+ * `priority` for LCP) or, when it has none, the mockup for its kind. Kind:
+ * `kind` prop → `resolveKind` (prop, then `MockupProvider`) → `resolveMockupKind`.
+ *
+ * The mockup's accessible name always says it is an illustration; `alt=""`
+ * makes it decorative (`aria-hidden`), like an empty `alt` on an image.
+ */
+declare function ProductImage({ product, variant, image, kind: kindProp, resolveKind: resolveProp, registry: registryProp, labels: labelOverrides, alt, className, style, id, ...imageProps }: ProductImageProps): react.JSX.Element | null;
+
+/**
+ * One store mockup, in one file: which products it claims, what it reads from
+ * them and how it draws. Every field but `kind` and `render` is optional.
+ */
+type MockupDefinition<D = any> = {
+    /** Kind name (`supplement`, `tire`, `casco-moto`). Reusing a base kind replaces it. */
+    kind: MockupKind;
+    /**
+     * Claims a product for this kind. Checked in list order, before the SDK's
+     * guess (`guess`: `mockup_kind` attribute, tire/part attributes, words in
+     * type/category/tags). Omit it to rely on the guess or on `mockup_kind`.
+     */
+    match?: (product: MockupProduct, guess: MockupKind) => boolean;
+    /** Product (+ selected variant) → data for `render`. Default: the base extractor of the kind (generic data for new kinds). Never prices. */
+    data?: (product: MockupProduct, variant?: MockupVariant | null) => D;
+    /** Data → accessible name (prefix it with `labels.illustration`). Default: `describeMockup`. */
+    describe?: (data: D, labels: MockupLabels) => string;
+    /** The drawing: a component that returns a `<MockupFrame>` (or a base one: `SupplementMockup`…). */
+    render: MockupComponent<D>;
+};
+/** Typed, checked definition of a store mockup (throws on an invalid kind or a missing `render`). */
+declare function defineMockup<D = any>(definition: MockupDefinition<D>): MockupDefinition<D>;
+type CreateStoreMockupsOptions = {
+    /**
+     * Starting registry: `builtin` (default) keeps tire, part, supplement and
+     * generic for the kinds the store does not define; `none` starts empty (keep
+     * a `generic` among your definitions); or pass a registry to extend.
+     */
+    base?: 'builtin' | 'none' | MockupRegistry;
+    /** Interface words (`illustration`, `servings`…) for every mockup. */
+    labels?: Partial<MockupLabels>;
+};
+/** What `<MockupProvider {...storeMockups}>` takes. */
+type StoreMockups = {
+    registry: MockupRegistry;
+    resolveKind: ResolveMockupKind;
+    labels?: Partial<MockupLabels>;
+    /** Kinds defined by the store, in order. */
+    kinds: MockupKind[];
+};
+/**
+ * Builds the store's mockup setup from its definitions: a registry (base
+ * mockups + the store's, the store's win) and a `resolveKind` that asks each
+ * `match` in order and otherwise keeps the SDK's guess.
+ *
+ * ```tsx
+ * export const storeMockups = createStoreMockups([supplement, accessory])
+ * <MockupProvider {...storeMockups}>…</MockupProvider>
+ * ```
+ */
+declare function createStoreMockups(definitions: readonly MockupDefinition[], options?: CreateStoreMockupsOptions): StoreMockups;
+
+export { BUILTIN_MOCKUPS, type CreateStoreMockupsOptions, DEFAULT_MOCKUP_LABELS, GenericMockup, MOCKUP_MONO, MOCKUP_SIZE, MOCKUP_TOKENS, type MockupComponent, type MockupComponentProps, type MockupConfig, type MockupDefinition, MockupFrame, type MockupFrameProps, type MockupLabels, MockupProvider, type MockupProviderProps, type MockupRegistry, type MockupRenderer, type MockupRendererInput, MockupText, type MockupTextProps, type MockupTone, PartMockup, ProductImage, type ProductImageProduct, type ProductImageProps, ProductMockup, type ProductMockupProps, type ResolveMockupKind, type ResolvedMockupRenderer, type StoreMockups, SupplementMockup, TireMockup, createMockupRegistry, createStoreMockups, defaultMockupRegistry, defineMockup, describeMockup, fitMockupFontSize, mockupWordMax, registerMockup, tone, useMockupConfig, wrapMockupText };