@liquidcommerce/elements-sdk 2.7.27 → 2.7.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +3 -2
  2. package/dist/index.checkout.esm.js +7518 -8002
  3. package/dist/index.esm.js +12271 -12755
  4. package/dist/types/modules/checkout/checkout.commands.d.ts +1 -0
  5. package/dist/types/modules/ui-components/lce-element/lce-element.component.d.ts +1 -9
  6. package/dist/types/utils/format.d.ts +4 -0
  7. package/docs/v1/api/configuration.md +3 -3
  8. package/docs/v1/guides/accessibility.md +14 -31
  9. package/docs/v1/guides/theming.md +2 -2
  10. package/package.json +1 -1
  11. package/dist/types/modules/theme-provider/services/contrast-guard.service.d.ts +0 -19
  12. package/dist/types/utils/color-contrast.d.ts +0 -16
package/dist/types/modules/checkout/checkout.commands.d.ts CHANGED
@@ -65,5 +65,6 @@ export declare class CheckoutCommands extends BaseCommand {
65
65
  private syncCheckoutState;
66
66
  private refreshCheckout;
67
67
  private dataForCheckoutPrepare;
68
+ private normalizeForApi;
68
69
  getDetails(): ICheckoutDetailsEventData;
69
70
  }
package/dist/types/modules/ui-components/lce-element/lce-element.component.d.ts CHANGED
@@ -1,20 +1,12 @@
1
- import { type ComponentType } from '@/enums';
1
+ import type { ComponentType } from '@/enums';
2
2
  import { SafeHTMLElement } from '@/utils/dom-compat';
3
3
  export declare class LceElementComponent extends SafeHTMLElement {
4
4
  private _initialized;
5
5
  protected _container: ShadowRoot | null;
6
6
  private _wrappedComponentRerender;
7
- private _contentType;
8
- private _appliedContrastVariables;
9
- private _unregisterContrastGuard;
10
7
  constructor();
11
8
  initialize(contentType: ComponentType, contentElement: HTMLElement): void;
12
9
  rerender(context?: string): void;
13
- connectedCallback(): void;
14
- disconnectedCallback(): void;
15
- private applyContrastCorrections;
16
- private resolveSurfaceColor;
17
- private measureHostSurfaceColor;
18
10
  private applyBasicStyles;
19
11
  private isCSSStyleSheetSupported;
20
12
  private applyThemeStyles;
package/dist/types/utils/format.d.ts CHANGED
@@ -8,3 +8,7 @@ export declare function splitCategoryPath(catPath?: string): {
8
8
  category2: string;
9
9
  category3: string;
10
10
  };
11
+ export declare function normalizeEngravingLines(lines: readonly (string | null | undefined)[] | null | undefined): string[];
12
+ export declare function normalizeText<T extends string | null | undefined>(value: T): T;
13
+ export declare function normalizeEmail<T extends string | null | undefined>(value: T): T;
14
+ export declare function normalizeCode<T extends string | null | undefined>(value: T): T;
package/docs/v1/api/configuration.md CHANGED
@@ -86,9 +86,9 @@ interface IGlobalTheme {
86
86
  }
87
87
  ```
88
88
 
89
- > `inputBorderColor` and `focusRingColor` are optional. If you omit them — or supply a value that
90
- > fails contrast — the runtime contrast guard substitutes a compliant color. Set them explicitly to
91
- > keep those two details on-brand. See [Accessibility](../guides/accessibility.md).
89
+ > `inputBorderColor` and `focusRingColor` are optional. Omit them to keep the WCAG-compliant
90
+ > defaults, or set them explicitly to keep those two details on-brand — any value you supply is used
91
+ > as given, so check its contrast. See [Accessibility](../guides/accessibility.md).
92
92
 
93
93
  | Property | Type | Description |
94
94
  |----------|------|-------------|
package/docs/v1/guides/accessibility.md CHANGED
@@ -13,7 +13,7 @@ Accessibility is shared between the SDK and the host page:
13
13
  |---|---|
14
14
  | Roles, names and states of everything inside an element | Page structure: landmarks, heading order, `<html lang>` |
15
15
  | Keyboard operation of every control it renders | Contrast of your own content, and the surface you place elements on |
16
- | Focus movement into and out of its overlays | A theme whose colours are legible (the SDK corrects what it can, and logs when it does) |
16
+ | Focus movement into and out of its overlays | A theme whose colours meet the WCAG contrast minimums (the SDK renders your colours as given) |
17
17
  | Announcing its own content changes | Not hiding or `inert`-ing the element container |
18
18
  | Reflow down to a 320px viewport | Layout around the element at 400% zoom |
19
19
 
@@ -57,7 +57,8 @@ retailer closes the panel — arrow keys move focus and `Enter` commits.
57
57
  A 2px ring in `--focus-ring-color`, offset 2px from the control. Controls that span their
58
58
  container's full width use an inset ring instead, because an outward ring on those is clipped by
59
59
  the scrolling panel around them. On primary-coloured fills the ring switches to
60
- `--selected-text-color`, which is guaranteed legible against that fill.
60
+ `--selected-text-color`, the token already used for text on that fill — so setting the pair
61
+ `primaryColor` / `selectedTextColor` to a combination that clears 3:1 covers the ring too.
61
62
 
62
63
  The ring targets `:focus` as well as `:focus-visible`, so browsers without `:focus-visible`
63
64
  support still show it.
@@ -118,26 +119,18 @@ on render, and a live region recreated with its text already in place is not ann
118
119
  Element colours come from your theme, and a brand palette chosen to look right often does not
119
120
  clear WCAG: white on a mid-tone brand fill is around 3:1, well under the 4.5:1 body text needs.
120
121
 
121
- The SDK therefore **measures your theme at runtime and corrects the foreground when it fails**:
122
+ **The SDK renders the colours you supply exactly as given — it does not adjust them.** Contrast is
123
+ therefore yours to get right: check each foreground token against the surface the Element sits on
124
+ and make sure it reaches 4.5:1 for text (WCAG 1.4.3) and 3:1 for borders, icons and the focus ring
125
+ (WCAG 1.4.11).
122
126
 
123
- 1. The surface each element renders on is resolved — a themed token for overlays, otherwise the
124
- real background behind the element, measured from your page.
125
- 2. Each foreground token is checked against that surface: text, links, warning/error/success,
126
- input borders and the focus ring, plus on-primary text against `primaryColor`.
127
- 3. Failing tokens are shifted in lightness — same hue, same saturation, away from the background
128
- — until they pass 4.5:1 (text) or 3:1 (borders, focus ring).
129
- 4. Backgrounds, fills and brand colours are never changed. Compliant themes are untouched.
127
+ The tokens worth checking are `defaultTextColor`, `linkTextColor`, `warningColor`, `errorColor` and
128
+ `successColor` against `drawerBackgroundColor` (or whatever your page puts behind the Element), plus
129
+ `selectedTextColor` against `primaryColor` for text on brand-filled buttons and badges.
130
130
 
131
- Corrections are applied as inline custom properties on the element host and logged:
132
-
133
- ```
134
- Theme colour adjusted for accessibility: defaultTextColor was #FFFFFF (3.02:1 against #E7751E),
135
- which is below the required 4.5:1. Using #2B2B2B (4.69:1) instead. Set a compliant colour in
136
- your theme to control this yourself.
137
- ```
138
-
139
- **To keep full control of your palette, supply colours that already pass.** Two tokens exist for
140
- exactly that and are worth setting explicitly:
131
+ Every token ships with a default that already passes on a light surface. Two are easy to forget
132
+ because they are optional — leave them out to keep the compliant defaults, or set them explicitly to
133
+ keep those details on-brand:
141
134
 
142
135
  ```javascript
143
136
  customTheme: {
@@ -150,9 +143,6 @@ customTheme: {
150
143
  }
151
144
  ```
152
145
 
153
- The SDK cannot see through a background image: if an element sits on one, surface-relative
154
- corrections are skipped rather than guessed, and the contrast of that text is yours to get right.
155
-
156
146
  ### Zoom, reflow and text spacing
157
147
 
158
148
  Elements reflow down to a 320px CSS viewport (400% zoom on a 1280px screen) without horizontal
@@ -173,18 +163,11 @@ for (const region of document.querySelectorAll('[data-lce-live-region]')) {
173
163
  }
174
164
  ```
175
165
 
176
- **Contrast corrections** — inspect the element host:
177
-
178
- ```javascript
179
- document.querySelector('lce-element[product]').getAttribute('style');
180
- // "--default-text-color: #2b2b2b; --focus-ring-color: #163ca7; …"
181
- ```
182
-
183
166
  **Screen readers:** verify with VoiceOver (Safari/macOS), NVDA (Firefox/Windows) or TalkBack
184
167
  (Chrome/Android) — the pairings that matter most for a storefront.
185
168
 
186
169
  ## See Also
187
170
 
188
- - [Theming Guide](./theming.md) — the tokens the contrast guard reads
171
+ - [Theming Guide](./theming.md) — the colour tokens to check for contrast
189
172
  - [Best Practices](./best-practices.md)
190
173
  - [Browser Support](../reference/browser-support.md)
package/docs/v1/guides/theming.md CHANGED
@@ -29,8 +29,8 @@ const client = await Elements('YOUR_API_KEY', {
29
29
  successColor: '#28a745',
30
30
  drawerBackgroundColor: '#ffffff',
31
31
 
32
- // Optional. Omit either one and the runtime contrast guard picks a
33
- // WCAG-compliant value for you; set them to keep these details on-brand.
32
+ // Optional. Omit either one to keep the WCAG-compliant default;
33
+ // set them to keep these details on-brand.
34
34
  inputBorderColor: '#d4d4d8',
35
35
  focusRingColor: '#007bff'
36
36
  }
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "LiquidCommerce Elements SDK",
4
4
  "license": "UNLICENSED",
5
5
  "author": "LiquidCommerce Team",
6
- "version": "2.7.27",
6
+ "version": "2.7.28",
7
7
  "homepage": "https://docs.liquidcommerce.co/elements-sdk",
8
8
  "repository": {
9
9
  "type": "git",
package/dist/types/modules/theme-provider/services/contrast-guard.service.d.ts DELETED
@@ -1,19 +0,0 @@
1
- import type { IGlobalTheme } from '@/interfaces/configs';
2
- import { type IRgbColor } from '@/utils/color-contrast';
3
- interface IGuardedHost {
4
- apply: () => void;
5
- }
6
- export declare class ContrastGuardService {
7
- private readonly logger;
8
- private readonly hosts;
9
- private readonly reported;
10
- static getInstance(): ContrastGuardService;
11
- register(host: IGuardedHost): () => void;
12
- refreshAll(): void;
13
- computeOverrides(theme: Partial<IGlobalTheme> | undefined, surface: IRgbColor | null): Record<string, string>;
14
- private token;
15
- private correctAgainstAll;
16
- private correct;
17
- private report;
18
- }
19
- export {};
package/dist/types/utils/color-contrast.d.ts DELETED
@@ -1,16 +0,0 @@
1
- export interface IRgbColor {
2
- r: number;
3
- g: number;
4
- b: number;
5
- a: number;
6
- }
7
- export declare const TEXT_CONTRAST_MIN = 4.5;
8
- export declare const NON_TEXT_CONTRAST_MIN = 3;
9
- export declare function parseColor(value: string | null | undefined): IRgbColor | null;
10
- export declare function toHexColor({ r, g, b }: IRgbColor): string;
11
- export declare function compositeOver(foreground: IRgbColor, background: IRgbColor): IRgbColor;
12
- export declare function relativeLuminance({ r, g, b }: IRgbColor): number;
13
- export declare function contrastRatio(foreground: IRgbColor, background: IRgbColor): number;
14
- export declare function meetsContrast(foreground: IRgbColor, background: IRgbColor, minRatio: number): boolean;
15
- export declare function ensureContrast(foreground: IRgbColor, background: IRgbColor, minRatio: number): IRgbColor;
16
- export declare function ensureContrastAgainstAll(foreground: IRgbColor, backgrounds: IRgbColor[], minRatio: number): IRgbColor;