@neurodyn/room-viewer 0.0.33 → 0.1.1

package/dist/contract.d.ts

@@ -0,0 +1,168 @@
+import type { ComponentProps } from 'react';
+import type { RoomViewerDialog } from '@neurodyn/react-room-viewer';
+import type { RoomViewerResourceType } from '@neurodyn/react-room-viewer';
+import type { RoomViewerResourceTypeInput } from '@neurodyn/react-room-viewer';
+
+/** What the reader hands a parser besides the raw value. */
+declare interface AttributeParseContext {
+    /** Full attribute name, e.g. `data-neurodyn-room-viewer-api-key`. */
+    attribute: string
+}
+
+/**
+ * Whether an attribute must be set: always, never, or only while another
+ * attribute holds one of the listed values (`src` while `type` is `wallart`).
+ * `when` names a field of the same contract.
+ */
+declare type AttributeRequirement
+= | boolean
+| { readonly when: string, readonly is: readonly string[] }
+
+/** The tag that loads the self-initializing embed build from `src`. */
+export declare function buildEmbedScript(src: string): string;
+
+/** A copy-paste trigger button with the given attributes, in contract order and escaped. */
+export declare function buildRoomViewerTrigger(values: RoomViewerTriggerValues, options: TriggerSnippetOptions): string;
+
+/**
+ * The rows describing a trigger built from the same values, for the table
+ * beside the snippet; `extra` adds attributes the snippet leaves out.
+ */
+export declare function describeRoomViewerTrigger(values: RoomViewerTriggerValues, extra?: readonly (keyof RoomViewerTriggerValues)[]): RoomViewerTriggerRow[];
+
+/** A widget option that has no attribute: callbacks, controlled state, sessions. */
+declare interface OptionOnly {
+    readonly kind: 'option'
+    /** Why the option is programmatic only. */
+    readonly reason: string
+}
+
+/** What an attribute's parser produces. */
+declare type ParsedAttributeValue<Field> = Field extends TriggerAttribute<infer Value> ? Value : never
+
+export declare const ROOM_VIEWER_DIMENSION_UNITS: readonly ["m", "cm", "in"];
+
+export declare const ROOM_VIEWER_DISPLAY_UNITS: readonly ["cm", "in"];
+
+export declare const ROOM_VIEWER_EMBED_SCRIPT_URL = "https://cdn.neurodyn.ai/@neurodyn/room-viewer/dist/room-viewer.embed.min.js";
+
+export declare const ROOM_VIEWER_LANGUAGES: readonly ["en", "ru"];
+
+export declare const ROOM_VIEWER_RESOURCE_TYPES: readonly ["wallart", "rugs", "flooring", "wall-panel"];
+
+export declare const ROOM_VIEWER_SOURCES: readonly ["default", "shopify"];
+
+/** The wall-art trigger the docs and Connect show as an example. */
+export declare const ROOM_VIEWER_TRIGGER_EXAMPLE: {
+    readonly type: "wallart";
+    readonly src: "https://placehold.co/800x1200.png";
+    readonly name: "Sample Print";
+    readonly width: 1;
+    readonly height: 1.5;
+    readonly apiKey: "...";
+};
+
+export declare const roomViewerContract: TriggerContract<RoomViewerDialogProps, {
+readonly type: TriggerAttribute<RoomViewerResourceTypeInput | undefined>;
+readonly src: TriggerAttribute<string | undefined>;
+readonly tinuuid: TriggerAttribute<string | undefined>;
+readonly roomId: TriggerAttribute<string | undefined>;
+readonly name: TriggerAttribute<string | undefined>;
+readonly width: TriggerAttribute<number | undefined>;
+readonly height: TriggerAttribute<number | undefined>;
+readonly dimensionUnit: TriggerAttribute<"m" | "cm" | "in" | undefined>;
+readonly displayUnit: TriggerAttribute<"cm" | "in" | undefined>;
+readonly language: TriggerAttribute<"en" | "ru" | undefined>;
+readonly apiKey: TriggerAttribute<string | undefined>;
+readonly source: TriggerAttribute<"default" | "shopify" | undefined>;
+readonly disableClose: TriggerAttribute<boolean>;
+readonly widgetSession: OptionOnly;
+readonly open: OptionOnly;
+readonly defaultOpen: OptionOnly;
+readonly onOpenChange: OptionOnly;
+}>;
+
+/** Options of the room viewer dialog. */
+export declare interface RoomViewerDialogProps extends Omit<ComponentProps<typeof RoomViewerDialog>, 'rooms'> {
+}
+
+export declare type RoomViewerTriggerRow = TriggerSnippetRow<keyof RoomViewerTriggerValues>;
+
+/**
+ * Values for a copy-paste trigger. Snippets only use canonical Resource Types:
+ * the legacy aliases keep working on merchant pages but are never generated.
+ */
+export declare type RoomViewerTriggerValues = Omit<TriggerSnippetValues<typeof roomViewerContract.fields>, 'type'> & {
+    type?: RoomViewerResourceType;
+};
+
+/** A widget option a merchant can set with a `data-*` attribute on the trigger. */
+declare interface TriggerAttribute<Value> {
+    readonly kind: 'attribute'
+    /** Attribute name without the widget prefix, e.g. `api-key`. */
+    readonly name: string
+    readonly parse: (raw: string | null, context: AttributeParseContext) => Value
+    /** The accepted values, listed in the docs. */
+    readonly values?: readonly string[]
+    /** What the docs and the cabinets' snippets ask for; the reader does not enforce it. */
+    readonly required: AttributeRequirement
+    /** The default as Markdown for the docs, e.g. `` `cm` `` or `User locale`. */
+    readonly defaultValue?: string
+    /** One or two sentences for the docs; accepted values are appended from `values`. */
+    readonly description: string
+    /** Full attribute names read, in order, while the primary one is absent or blank. */
+    readonly legacyNames?: readonly string[]
+    /** Runs an explicitly passed programmatic option through `parse` as well. */
+    readonly normalizesOptions?: boolean
+}
+
+/** Keys of the fields that are attributes. */
+declare type TriggerAttributeKey<Fields> = {
+    [Key in keyof Fields]: Fields[Key] extends TriggerAttribute<any> ? Key : never
+}[keyof Fields] & string
+
+declare interface TriggerContract<Options, Fields extends TriggerFields<Options> = TriggerFields<Options>> {
+    /** Prefix shared by the widget's option attributes, e.g. `data-neurodyn-room-viewer-`. */
+    readonly prefix: string
+    /** The first marker is the one snippets use. */
+    readonly markers: readonly [TriggerMarker, ...TriggerMarker[]]
+    readonly fields: Fields
+}
+
+/**
+ * One entry per widget option, none optional: an option added to the widget's
+ * props without an entry here fails type-checking until it is given an
+ * attribute or marked option-only.
+ */
+declare type TriggerFields<Options> = {
+    readonly [Key in keyof Options]-?: TriggerAttribute<Options[Key] | undefined> | OptionOnly
+}
+
+/** A marker attribute that selects trigger elements, e.g. `data-neurodyn-room-viewer-dialog`. */
+declare interface TriggerMarker {
+    readonly name: string
+    readonly description: string
+}
+
+export declare interface TriggerSnippetOptions {
+    /** The button text. */
+    label: string
+}
+
+/** One attribute of a snippet, for the table next to it. */
+declare interface TriggerSnippetRow<Key extends string> {
+    /** The field key, or `null` for the marker attribute. */
+    key: Key | null
+    attribute: string
+    required: boolean
+}
+
+/**
+ * Values for a copy-paste trigger: only the contract's attributes, each typed
+ * as its option. Placeholders such as `PUBLIC_WIDGET_KEY` fit string options.
+ */
+declare type TriggerSnippetValues<Fields> = {
+    [Key in TriggerAttributeKey<Fields>]?: Exclude<ParsedAttributeValue<Fields[Key]>, undefined | null>
+}
+
+export { }

package/dist/contract.js

@@ -0,0 +1,230 @@
+function contract_attribute(name, parser, details) {
+    return {
+        kind: 'attribute',
+        name,
+        parse: parser.parse,
+        values: parser.values,
+        ...details
+    };
+}
+function optionOnly(reason) {
+    return {
+        kind: 'option',
+        reason
+    };
+}
+function defineTriggerContract() {
+    return (contract)=>contract;
+}
+function contract_attributeEntries(contract) {
+    return Object.entries(contract.fields).filter((entry)=>'attribute' === entry[1].kind);
+}
+function escapeHtml(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function isAttributeRequired(requirement, values) {
+    if ('boolean' == typeof requirement) return requirement;
+    const current = values[requirement.when];
+    return null != current && requirement.is.includes(String(current));
+}
+function snippetEntries(contract, values) {
+    return contract_attributeEntries(contract).flatMap(([key, field])=>{
+        const value = values[key];
+        return null == value ? [] : [
+            {
+                key,
+                field,
+                value
+            }
+        ];
+    });
+}
+function snippet_buildTriggerSnippet(contract, values, { label }) {
+    const lines = [
+        '<button',
+        '  type="button"',
+        `  ${contract.markers[0].name}`
+    ];
+    for (const { field, value } of snippetEntries(contract, values))lines.push(`  ${contract.prefix}${field.name}="${escapeHtml(String(value))}"`);
+    lines.push('>', `  ${escapeHtml(label)}`, '</button>');
+    return lines.join('\n');
+}
+function describeTriggerSnippet(contract, values, extra = []) {
+    const present = snippetEntries(contract, values);
+    const presentKeys = new Set(present.map(({ key })=>key));
+    const fields = contract.fields;
+    const row = (key, field)=>({
+            key,
+            attribute: `${contract.prefix}${field.name}`,
+            required: isAttributeRequired(field.required, values)
+        });
+    return [
+        {
+            key: null,
+            attribute: contract.markers[0].name,
+            required: true
+        },
+        ...present.map(({ key, field })=>row(key, field)),
+        ...extra.filter((key)=>!presentKeys.has(key)).map((key)=>row(key, fields[key]))
+    ];
+}
+function snippet_buildEmbedScript(src) {
+    return `<script defer src="${escapeHtml(src)}"></script>`;
+}
+function parsers_text() {
+    return {
+        parse: (raw)=>raw ?? void 0
+    };
+}
+function number() {
+    return {
+        parse: (raw)=>raw ? Number(raw) : void 0
+    };
+}
+function flag() {
+    return {
+        parse: (raw)=>'true' === raw
+    };
+}
+function oneOf(values) {
+    return {
+        parse: (raw)=>values.includes(raw ?? '') ? raw : void 0,
+        values
+    };
+}
+function unchecked(values) {
+    return {
+        parse: (raw)=>raw ?? void 0,
+        values
+    };
+}
+function listOf() {
+    return (values)=>values;
+}
+const ROOM_VIEWER_TRIGGER_ATTRIBUTE = 'data-neurodyn-room-viewer-dialog';
+const ROOM_VIEWER_RESOURCE_TYPES = listOf()([
+    'wallart',
+    'rugs',
+    'flooring',
+    'wall-panel'
+]);
+const ROOM_VIEWER_DIMENSION_UNITS = listOf()([
+    'm',
+    'cm',
+    'in'
+]);
+const ROOM_VIEWER_DISPLAY_UNITS = listOf()([
+    'cm',
+    'in'
+]);
+const ROOM_VIEWER_LANGUAGES = listOf()([
+    'en',
+    'ru'
+]);
+const ROOM_VIEWER_SOURCES = listOf()([
+    'default',
+    'shopify'
+]);
+const ROOM_VIEWER_EMBED_SCRIPT_URL = 'https://cdn.neurodyn.ai/@neurodyn/room-viewer/dist/room-viewer.embed.min.js';
+const roomViewerContract = defineTriggerContract()({
+    prefix: 'data-neurodyn-room-viewer-',
+    markers: [
+        {
+            name: ROOM_VIEWER_TRIGGER_ATTRIBUTE,
+            description: 'Marks an element for the embed build.'
+        }
+    ],
+    fields: {
+        type: contract_attribute('type', unchecked(ROOM_VIEWER_RESOURCE_TYPES), {
+            required: true,
+            description: 'Resource type.'
+        }),
+        src: contract_attribute('src', parsers_text(), {
+            required: {
+                when: 'type',
+                is: [
+                    'wallart'
+                ]
+            },
+            description: 'Wall-art image URL.'
+        }),
+        tinuuid: contract_attribute('tinuuid', parsers_text(), {
+            required: {
+                when: 'type',
+                is: [
+                    'rugs',
+                    'flooring',
+                    'wall-panel'
+                ]
+            },
+            description: 'The object\'s tinuuid.'
+        }),
+        roomId: contract_attribute('room-id', parsers_text(), {
+            required: false,
+            description: 'Initial Room ID from the available catalog. Skips the initial interior chooser; unavailable Rooms open the chooser. Empty values do nothing.'
+        }),
+        name: contract_attribute('name', parsers_text(), {
+            required: true,
+            description: 'Title shown in the dialog header.'
+        }),
+        width: contract_attribute('width', number(), {
+            required: false,
+            description: 'Wall-art width. Used when `type` is `wallart`.'
+        }),
+        height: contract_attribute('height', number(), {
+            required: false,
+            description: 'Wall-art height. Used when `type` is `wallart`.'
+        }),
+        dimensionUnit: contract_attribute('dimension-unit', oneOf(ROOM_VIEWER_DIMENSION_UNITS), {
+            required: false,
+            defaultValue: '`m`',
+            description: 'Unit used by wall-art width and height.'
+        }),
+        displayUnit: contract_attribute('display-unit', oneOf(ROOM_VIEWER_DISPLAY_UNITS), {
+            required: false,
+            defaultValue: '`cm`',
+            description: 'Unit used to display UI measurements.'
+        }),
+        language: contract_attribute('language', oneOf(ROOM_VIEWER_LANGUAGES), {
+            required: false,
+            defaultValue: 'User locale',
+            description: 'UI language override.'
+        }),
+        apiKey: contract_attribute('api-key', parsers_text(), {
+            required: true,
+            description: 'Public API key sent as `x-api-key`. Not needed when `source` is `shopify`.'
+        }),
+        source: contract_attribute('source', oneOf(ROOM_VIEWER_SOURCES), {
+            required: false,
+            defaultValue: '`default`',
+            description: 'Backend source mode.'
+        }),
+        disableClose: contract_attribute('disable-close', flag(), {
+            required: false,
+            defaultValue: '`false`',
+            description: 'Set to `true` to hide close controls and prevent dismissal.'
+        }),
+        widgetSession: optionOnly('An existing Widget Session handed over by an embedding surface such as Shopify.'),
+        open: optionOnly('The embed build owns the open state.'),
+        defaultOpen: optionOnly('The embed build owns the open state.'),
+        onOpenChange: optionOnly('The embed build owns the open state.')
+    }
+});
+const ROOM_VIEWER_TRIGGER_EXAMPLE = {
+    type: 'wallart',
+    src: 'https://placehold.co/800x1200.png',
+    name: 'Sample Print',
+    width: 1,
+    height: 1.5,
+    apiKey: '...'
+};
+function buildRoomViewerTrigger(values, options) {
+    return snippet_buildTriggerSnippet(roomViewerContract, values, options);
+}
+function describeRoomViewerTrigger(values, extra = []) {
+    return describeTriggerSnippet(roomViewerContract, values, extra);
+}
+function contract_buildEmbedScript(src) {
+    return snippet_buildEmbedScript(src);
+}
+export { ROOM_VIEWER_DIMENSION_UNITS, ROOM_VIEWER_DISPLAY_UNITS, ROOM_VIEWER_EMBED_SCRIPT_URL, ROOM_VIEWER_LANGUAGES, ROOM_VIEWER_RESOURCE_TYPES, ROOM_VIEWER_SOURCES, ROOM_VIEWER_TRIGGER_EXAMPLE, contract_buildEmbedScript as buildEmbedScript, buildRoomViewerTrigger, describeRoomViewerTrigger, roomViewerContract };

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export declare class RoomViewerDialog {
 declare interface RoomViewerDialogOptions extends Partial<RoomViewerDialogProps> {
 }
 
+/** Options of the room viewer dialog. */
 declare interface RoomViewerDialogProps extends Omit<ComponentProps<typeof RoomViewerDialog_2>, 'rooms'> {
 }