@welcome-back/brand 0.2.0 → 0.3.0

package/README.md

@@ -19,6 +19,7 @@ Use it for loading moments that mean "on the way to the next step".
 - [API](#api)
 - [Examples](#examples)
 - [POS design tokens](#pos-design-tokens)
+- [Product image frames](#product-image-frames)
 - [Accessibility](#accessibility)
 - [Where to use it, and where not](#where-to-use-it-and-where-not)
 - [Troubleshooting](#troubleshooting)
@@ -319,6 +320,28 @@ POS_TOKENS['--wb-accent']; // '#171717'
 
 `posTokensCss(selector)` returns the same rule for another selector.
 
+## Product image frames
+
+The frames a product photo is shown in: `1:1`, `4:3`, `3:2`, `16:9`. The
+dashboard cropper saves one square photo. The digital menu, the kiosk and the
+POS show it centered with `object-cover` in one of these frames, and the cropper
+draws a guide for each one. So what the owner crops is what each surface shows.
+
+A surface that shows a product photo in a frame outside this list breaks that
+promise. Add the frame here, or use one that is already here.
+
+```tsx
+import {
+  productImageAspectRatio,
+  productImageKeptArea,
+} from '@welcome-back/brand';
+
+<div style={{ aspectRatio: productImageAspectRatio('4:3') }}>…</div>;
+productImageKeptArea('16:9'); // { width: 1, height: 0.5625 } of the square, centered
+```
+
+`PRODUCT_IMAGE_FRAMES` holds the raw `{ width, height }` of each frame.
+
 ## Accessibility
 
 - **Give exactly one accessible name per loading state.** Either put `label` on

package/dist/cjs/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.posTokensCss = exports.POS_TOKENS = exports.RunnerLoader = void 0;
+exports.productImageKeptArea = exports.productImageAspectRatio = exports.PRODUCT_IMAGE_FRAMES = exports.posTokensCss = exports.POS_TOKENS = exports.RunnerLoader = void 0;
 var RunnerLoader_js_1 = require("./RunnerLoader.js");
 Object.defineProperty(exports, "RunnerLoader", { enumerable: true, get: function () { return RunnerLoader_js_1.RunnerLoader; } });
 var posTokens_js_1 = require("./posTokens.js");
 Object.defineProperty(exports, "POS_TOKENS", { enumerable: true, get: function () { return posTokens_js_1.POS_TOKENS; } });
 Object.defineProperty(exports, "posTokensCss", { enumerable: true, get: function () { return posTokens_js_1.posTokensCss; } });
+var productImageFrames_js_1 = require("./productImageFrames.js");
+Object.defineProperty(exports, "PRODUCT_IMAGE_FRAMES", { enumerable: true, get: function () { return productImageFrames_js_1.PRODUCT_IMAGE_FRAMES; } });
+Object.defineProperty(exports, "productImageAspectRatio", { enumerable: true, get: function () { return productImageFrames_js_1.productImageAspectRatio; } });
+Object.defineProperty(exports, "productImageKeptArea", { enumerable: true, get: function () { return productImageFrames_js_1.productImageKeptArea; } });

package/dist/cjs/productImageFrames.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRODUCT_IMAGE_FRAMES = void 0;
+exports.productImageAspectRatio = productImageAspectRatio;
+exports.productImageKeptArea = productImageKeptArea;
+/**
+ * The frames a product photo is shown in. The dashboard cropper saves one
+ * square photo; the digital menu (catalog-ui), the kiosk and the POS show it
+ * centered with `object-cover` in one of these frames. The cropper draws a
+ * guide for each frame, so what the owner crops is what each surface shows.
+ *
+ * A surface that shows a product photo in a frame outside this list breaks
+ * that promise: add the frame here, or use one that is already here.
+ */
+exports.PRODUCT_IMAGE_FRAMES = {
+    "1:1": { width: 1, height: 1 },
+    "4:3": { width: 4, height: 3 },
+    "3:2": { width: 3, height: 2 },
+    "16:9": { width: 16, height: 9 },
+};
+/** CSS `aspect-ratio` value for a frame, e.g. `"4 / 3"`. */
+function productImageAspectRatio(frame) {
+    const { width, height } = exports.PRODUCT_IMAGE_FRAMES[frame];
+    return `${width} / ${height}`;
+}
+/**
+ * The part of the square photo a frame keeps, centered, as fractions of the
+ * square's side. Every frame is as wide as or wider than it is tall, so it
+ * keeps the full width and cuts the top and bottom equally.
+ */
+function productImageKeptArea(frame) {
+    const { width, height } = exports.PRODUCT_IMAGE_FRAMES[frame];
+    return { width: 1, height: height / width };
+}

package/dist/esm/index.d.ts

@@ -2,3 +2,5 @@ export { RunnerLoader } from "./RunnerLoader.js";
 export type { RunnerLoaderProps } from "./RunnerLoader.js";
 export { POS_TOKENS, posTokensCss } from "./posTokens.js";
 export type { PosToken } from "./posTokens.js";
+export { PRODUCT_IMAGE_FRAMES, productImageAspectRatio, productImageKeptArea, } from "./productImageFrames.js";
+export type { ProductImageFrame } from "./productImageFrames.js";

package/dist/esm/index.js

@@ -1,2 +1,3 @@
 export { RunnerLoader } from "./RunnerLoader.js";
 export { POS_TOKENS, posTokensCss } from "./posTokens.js";
+export { PRODUCT_IMAGE_FRAMES, productImageAspectRatio, productImageKeptArea, } from "./productImageFrames.js";

package/dist/esm/productImageFrames.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The frames a product photo is shown in. The dashboard cropper saves one
+ * square photo; the digital menu (catalog-ui), the kiosk and the POS show it
+ * centered with `object-cover` in one of these frames. The cropper draws a
+ * guide for each frame, so what the owner crops is what each surface shows.
+ *
+ * A surface that shows a product photo in a frame outside this list breaks
+ * that promise: add the frame here, or use one that is already here.
+ */
+export declare const PRODUCT_IMAGE_FRAMES: {
+    readonly "1:1": {
+        readonly width: 1;
+        readonly height: 1;
+    };
+    readonly "4:3": {
+        readonly width: 4;
+        readonly height: 3;
+    };
+    readonly "3:2": {
+        readonly width: 3;
+        readonly height: 2;
+    };
+    readonly "16:9": {
+        readonly width: 16;
+        readonly height: 9;
+    };
+};
+export type ProductImageFrame = keyof typeof PRODUCT_IMAGE_FRAMES;
+/** CSS `aspect-ratio` value for a frame, e.g. `"4 / 3"`. */
+export declare function productImageAspectRatio(frame: ProductImageFrame): string;
+/**
+ * The part of the square photo a frame keeps, centered, as fractions of the
+ * square's side. Every frame is as wide as or wider than it is tall, so it
+ * keeps the full width and cuts the top and bottom equally.
+ */
+export declare function productImageKeptArea(frame: ProductImageFrame): {
+    width: number;
+    height: number;
+};

package/dist/esm/productImageFrames.js

@@ -0,0 +1,29 @@
+/**
+ * The frames a product photo is shown in. The dashboard cropper saves one
+ * square photo; the digital menu (catalog-ui), the kiosk and the POS show it
+ * centered with `object-cover` in one of these frames. The cropper draws a
+ * guide for each frame, so what the owner crops is what each surface shows.
+ *
+ * A surface that shows a product photo in a frame outside this list breaks
+ * that promise: add the frame here, or use one that is already here.
+ */
+export const PRODUCT_IMAGE_FRAMES = {
+    "1:1": { width: 1, height: 1 },
+    "4:3": { width: 4, height: 3 },
+    "3:2": { width: 3, height: 2 },
+    "16:9": { width: 16, height: 9 },
+};
+/** CSS `aspect-ratio` value for a frame, e.g. `"4 / 3"`. */
+export function productImageAspectRatio(frame) {
+    const { width, height } = PRODUCT_IMAGE_FRAMES[frame];
+    return `${width} / ${height}`;
+}
+/**
+ * The part of the square photo a frame keeps, centered, as fractions of the
+ * square's side. Every frame is as wide as or wider than it is tall, so it
+ * keeps the full width and cuts the top and bottom equally.
+ */
+export function productImageKeptArea(frame) {
+    const { width, height } = PRODUCT_IMAGE_FRAMES[frame];
+    return { width: 1, height: height / width };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@welcome-back/brand",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "WelcomeBack brand assets for React apps: the running-W loader and the POS design tokens.",
   "license": "UNLICENSED",
   "repository": {