@scalewing/react 1.59.5 → 1.60.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.60.0
+
+### Minor Changes
+
+- 69e52f9: `PreviewImage`: a real screenshot inside a `ScreenPreview`, at the screen's width with its height following. Decorative, as the preview's `label` names the image (Teisoro F-017 task 2730).
+
 ## 1.59.5
 
 ### Patch Changes

package/README.md

@@ -39,6 +39,7 @@ import {
   Hero,
   ScreenPreview,
   PreviewGroup,
+  PreviewImage,
   PreviewRow,
   PreviewTiles,
   SiteFooter,
@@ -1176,6 +1177,8 @@ const { headings, omissions } = inspectMarkdown(page.body, {
 
 `ScreenPreview` is a drawn stand-in for an app's screen on a public page, until a real screenshot replaces it: a `figure` whose screen is one image (`role="img"`) named by `label`, its alternative text, so a screen reader hears that sentence instead of the rows; an optional `caption` shows under it as the `figcaption`. An optional `eyebrow` and `title` head the screen. Its content is `PreviewGroup`s of `PreviewRow`s (`label` at the start, `value` at the end in tabular numerals; `kind` `plain`, `total` in bold past a hairline, `note` a small label over its words, `filled` on the quiet fill, or `alert` on the danger tint) and `PreviewTiles` (`items` of `{ id, label, value }`, three to a row on a phone, six from `md`). `frame="card"` (default) is a surface card whose groups are parted by hairlines; `frame="device"` draws a 20rem phone from `md` (a bezel in the text colour round a quiet screen with a surface header and each group a card) and the card below `md`. A blank `label`, an unknown `frame` or `kind`, no tiles, or a blank or repeated tile id throws a `RangeError`.
 
+When the real screenshot exists, a `PreviewImage` (`src`, `width`, `height`) holds it in the same frame, filling the screen's body with its height following. It is decorative: `label` stays the alternative text.
+
 ```tsx
 <ScreenPreview
   frame="device"

package/dist/components/ScreenPreview.d.ts

@@ -12,14 +12,15 @@ export type ScreenPreviewProps = Omit<HTMLAttributes<HTMLElement>, 'children' |
     title?: ReactNode;
     /** A visible caption under the screen, such as what will replace it. */
     caption?: ReactNode;
-    /** `PreviewGroup`s, `PreviewRow`s and `PreviewTiles`. */
+    /** `PreviewGroup`s, `PreviewRow`s, `PreviewTiles` or a `PreviewImage`. */
     children: ReactNode;
 };
 /**
  * A drawn stand-in for an app's screen on a public page: a `figure` whose
  * screen is one image (`role="img"`) named by `label`, so its rows are
  * read as that one sentence, with an optional visible `caption`. Its
- * content is `PreviewGroup`s of `PreviewRow`s and `PreviewTiles`. A blank
+ * content is `PreviewGroup`s of `PreviewRow`s, `PreviewTiles` or a
+ * `PreviewImage` holding a real screenshot. A blank
  * label or an unknown frame throws a `RangeError`.
  */
 export declare function ScreenPreview({ caption, children, className, eyebrow, frame, label, title, ...rest }: ScreenPreviewProps): import("react").JSX.Element;

package/dist/components/ScreenPreview.js

@@ -7,7 +7,8 @@ export { screenPreviewFrames };
  * A drawn stand-in for an app's screen on a public page: a `figure` whose
  * screen is one image (`role="img"`) named by `label`, so its rows are
  * read as that one sentence, with an optional visible `caption`. Its
- * content is `PreviewGroup`s of `PreviewRow`s and `PreviewTiles`. A blank
+ * content is `PreviewGroup`s of `PreviewRow`s, `PreviewTiles` or a
+ * `PreviewImage` holding a real screenshot. A blank
  * label or an unknown frame throws a `RangeError`.
  */
 export function ScreenPreview({ caption, children, className, eyebrow, frame = 'card', label, title, ...rest }) {

package/dist/components/screen-preview/PreviewImage.d.ts

@@ -0,0 +1,13 @@
+/** The file and its natural size in pixels, so the page keeps its place while it loads. */
+export type PreviewImageProps = {
+    src: string;
+    width: number;
+    height: number;
+};
+/**
+ * A real screenshot inside a `ScreenPreview`, drawn at the width of the
+ * screen with its height following. It is decorative (`alt=""`): the
+ * preview's `label` already says what it shows. A blank `src` or a size
+ * that is not a positive whole number throws a `RangeError`.
+ */
+export declare function PreviewImage({ height, src, width }: PreviewImageProps): import("react").JSX.Element;

package/dist/components/screen-preview/PreviewImage.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A real screenshot inside a `ScreenPreview`, drawn at the width of the
+ * screen with its height following. It is decorative (`alt=""`): the
+ * preview's `label` already says what it shows. A blank `src` or a size
+ * that is not a positive whole number throws a `RangeError`.
+ */
+export function PreviewImage({ height, src, width }) {
+    if (!src.trim())
+        throw new RangeError('A PreviewImage needs a src');
+    for (const [name, side] of [
+        ['width', width],
+        ['height', height],
+    ])
+        if (!Number.isInteger(side) || side <= 0)
+            throw new RangeError(`A PreviewImage's ${name} must be a positive whole number, not ${side}`);
+    return (_jsx("img", { alt: "", className: "sw-preview-image", height: height, loading: "lazy", src: src, width: width }));
+}

package/dist/css/css-fixture-action.js

@@ -2,9 +2,11 @@ import { mutedReadsAsText, quietFill } from './quiet-fill.js';
 /*
  * The action sits after the row in its own column, centred on the row's
  * height, outside the row's press area, keeping the row's end padding
- * after it. Where :has() is supported the hover fill spans the whole item,
- * so the row, its select and its action read as one line; a detail under
- * the row is on that fill too, so its muted words take the text colour.
+ * after it. It ends at the column's end, so a short action on one row and
+ * a long one on the next finish on the same line. Where :has() is supported
+ * the hover fill spans the whole item, so the row, its select and its action
+ * read as one line; a detail under the row is on that fill too, so its muted
+ * words take the text colour.
  */
 function actionRules() {
     return `.sw-fixture-action {
@@ -13,6 +15,7 @@ function actionRules() {
   display: inline-flex;
   grid-column: -2 / -1;
   grid-row: 1;
+  justify-content: flex-end;
   padding-inline-end: var(--sw-space-2);
 }
 

package/dist/css/css-screen-preview.js

@@ -87,6 +87,16 @@ function cardRules() {
   line-height: ${caption.lineHeight}px;
 }`;
 }
+/* A screenshot fills the screen's width; its height follows. */
+function imageRules() {
+    return `.sw-preview-image {
+  border-radius: var(--sw-radius-sm);
+  display: block;
+  height: auto;
+  max-width: 100%;
+  width: 100%;
+}`;
+}
 function rowRules() {
     return `.sw-preview-row {
   display: flex;
@@ -206,7 +216,7 @@ function wideRules() {
 }`;
 }
 export function cssScreenPreviewClasses() {
-    return [cardRules(), rowRules(), wideRules()].join('\n\n');
+    return [cardRules(), imageRules(), rowRules(), wideRules()].join('\n\n');
 }
 export function screenPreviewClassCatalog() {
     return [
@@ -224,6 +234,7 @@ export function screenPreviewClassCatalog() {
         ...previewRowKinds.map(previewRowKindClass),
         'sw-preview-row-label',
         'sw-preview-row-value',
+        'sw-preview-image',
         'sw-preview-tiles',
         'sw-preview-tile',
         'sw-preview-tile-label',

package/dist/index.d.ts

@@ -90,6 +90,8 @@ export type { SiteHeaderItem, SiteHeaderLabels, SiteHeaderProps, SiteHeaderSkipL
 export { ScreenPreview, screenPreviewFrames, } from './components/ScreenPreview.js';
 export type { ScreenPreviewFrame, ScreenPreviewProps, } from './components/ScreenPreview.js';
 export { PreviewGroup } from './components/screen-preview/PreviewGroup.js';
+export { PreviewImage } from './components/screen-preview/PreviewImage.js';
+export type { PreviewImageProps } from './components/screen-preview/PreviewImage.js';
 export { PreviewRow, previewRowKinds, } from './components/screen-preview/PreviewRow.js';
 export type { PreviewRowKind, PreviewRowProps, } from './components/screen-preview/PreviewRow.js';
 export { PreviewTiles } from './components/screen-preview/PreviewTiles.js';

package/dist/index.js

@@ -81,6 +81,7 @@ export { Band, bandElements, bandTones, bandWidths, } from './components/Band.js
 export { SiteHeader } from './components/SiteHeader.js';
 export { ScreenPreview, screenPreviewFrames, } from './components/ScreenPreview.js';
 export { PreviewGroup } from './components/screen-preview/PreviewGroup.js';
+export { PreviewImage } from './components/screen-preview/PreviewImage.js';
 export { PreviewRow, previewRowKinds, } from './components/screen-preview/PreviewRow.js';
 export { PreviewTiles } from './components/screen-preview/PreviewTiles.js';
 export { Hero } from './components/Hero.js';

package/dist/styles.css

@@ -3618,6 +3618,7 @@ button.sw-date-toggle-day[aria-disabled='true'] {
   display: inline-flex;
   grid-column: -2 / -1;
   grid-row: 1;
+  justify-content: flex-end;
   padding-inline-end: var(--sw-space-2);
 }
 
@@ -5299,6 +5300,14 @@ button.sw-date-toggle-day[aria-disabled='true'] {
   line-height: 18px;
 }
 
+.sw-preview-image {
+  border-radius: var(--sw-radius-sm);
+  display: block;
+  height: auto;
+  max-width: 100%;
+  width: 100%;
+}
+
 .sw-preview-row {
   display: flex;
   gap: var(--sw-space-3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.59.5",
+  "version": "1.60.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",