@marianmeres/stuic 3.193.0 → 3.194.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 83 component directories
+├── components/     # 84 component directories
 ├── actions/        # 16 Svelte actions (use: directives)
 ├── attachments/    # Svelte attachments ({@attach} — preferred for new DOM helpers)
 ├── utils/          # 55 utility modules (48 on the barrel)
@@ -146,7 +146,7 @@ so it is the only confusable pair — do not "fix" one into the other.
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 83 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 84 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [CSS presets](./docs/domains/css-presets.md) — ratio-locked frame (letterbox), safe-area, scrollbar
 - [Actions](./docs/domains/actions.md) — 16 Svelte directives

package/API.md

@@ -1363,6 +1363,30 @@ interface ImageCyclerImage {
 }
 ```
 
+#### `PhoneFrame`
+
+Phone-shaped bezel around a screenshot (`src`) or any content (`children`). Block-level, sized with `class`; the screen is locked to a `390 / 844` ratio unless `screenHeight` turns it into a fixed-height window showing the top of the content. With `href` the whole frame is a link.
+
+| Prop            | Type                            | Default  | Description                                                                 |
+| --------------- | ------------------------------- | -------- | --------------------------------------------------------------------------- |
+| `src`           | `string`                        | —        | Screenshot URL (`object-fit: cover`, anchored to the top)                   |
+| `alt`           | `string`                        | `""`     | Alt text; the link's accessible name with `href`                            |
+| `width`         | `number \| string`              | —        | Intrinsic pixel width of the screenshot (`<img width>`), not the frame size |
+| `height`        | `number \| string`              | —        | Intrinsic pixel height of the screenshot (`<img height>`)                   |
+| `srcset`        | `string`                        | —        | `<img srcset>` pass-through                                                 |
+| `sizes`         | `string`                        | —        | `<img sizes>` pass-through                                                  |
+| `loading`       | `"lazy" \| "eager"`             | `"lazy"` | `eager` for a hero screenshot                                               |
+| `fetchpriority` | `"high" \| "low" \| "auto"`     | —        | `<img fetchpriority>` pass-through                                          |
+| `children`      | `Snippet`                       | —        | Custom screen content; takes precedence over `src`                          |
+| `href`          | `string`                        | —        | Renders `<a>` instead of `<div>`                                            |
+| `target`        | `string`                        | —        | Link target                                                                 |
+| `rel`           | `string`                        | —        | Link rel; `"noopener"` by default when `target` is `"_blank"`               |
+| `aspectRatio`   | `string \| number`              | token    | Screen `aspect-ratio` (`"390 / 844"`); ignored while `screenHeight` is set  |
+| `screenHeight`  | `string`                        | —        | Fixed screen height: a clipped window of the top of the content             |
+| `notch`         | `"none" \| "island" \| "notch"` | `"none"` | Camera cutout over the top of the screen                                    |
+| `classScreen`   | `string`                        | —        | Classes for the screen (clipping window)                                    |
+| `classImage`    | `string`                        | —        | Classes for the `<img>`                                                     |
+
 #### `ThemePreview`
 
 Theme color swatch preview.
@@ -2503,6 +2527,7 @@ Each component defines customization tokens. Override globally in `:root {}` or
 | Notifications      | `--stuic-notification-*`        | `bg`, `text`, `border`                                                                                                                                                                                                        |
 | Tooltip            | `--stuic-tooltip-*`             | `bg`, `text`                                                                                                                                                                                                                  |
 | Popover            | `--stuic-popover-*`             | `bg`, `text`, `border`                                                                                                                                                                                                        |
+| PhoneFrame         | `--stuic-phone-frame-*`         | `bg`, `padding`, `radius`, `border-color`, `shadow`, `screen-bg`, `screen-radius`, `screen-aspect-ratio`, `screen-height`, `island-width`, `island-top`, `notch-width`, `notch-radius`, `notch-bg`, `ring-color`              |
 | Skeleton           | `--stuic-skeleton-*`            | `bg`, `bg-highlight`, `duration`                                                                                                                                                                                              |
 | Spotlight          | `--stuic-spotlight-*`           | `backdrop-bg`, `annotation-bg`, `annotation-text`, `annotation-border`                                                                                                                                                        |
 | Cart               | `--stuic-cart-*`                | `gap`, `item-padding`, `item-radius`, `item-border-color`, `item-bg`, `thumbnail-size`, `quantity-border-color`, `remove-color`, `summary-border-color`, `compact-max-height`, `transition`                                   |

package/README.md

@@ -191,7 +191,7 @@ CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 
 ### Display & Utility
 
-Avatar, Pill, Book, BookResponsive, Card, Carousel, Circle, AnimatedElipsis, H, IconSwap, ImageCycler, Separator, ThemePreview, Tree, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
+Avatar, Pill, Book, BookResponsive, Card, Carousel, Circle, AnimatedElipsis, H, IconSwap, ImageCycler, PhoneFrame, Separator, ThemePreview, Tree, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
 
 ### E-commerce
 

package/dist/components/EmptyState/index.css

@@ -12,7 +12,7 @@
 	--stuic-empty-state-padding-sm: 1.5rem;
 	--stuic-empty-state-icon-size-sm: 2rem;
 	--stuic-empty-state-title-font-size-sm: var(--text-base);
-	--stuic-empty-state-description-font-size-sm: var(--text-xs);
+	--stuic-empty-state-description-font-size-sm: var(--text-sm);
 
 	/* Size: md */
 	--stuic-empty-state-padding-md: 3rem;

package/dist/components/PhoneFrame/PhoneFrame.svelte

@@ -0,0 +1,165 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+
+	/** Camera cutout drawn over the top of the screen. */
+	export type PhoneFrameNotch = "none" | "island" | "notch";
+
+	export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children" | "class"> {
+		/**
+		 * Screenshot URL. The image fills the screen (`object-fit: cover`, anchored to the
+		 * top). Omit it and render your own content with `children` instead.
+		 */
+		src?: string;
+		/** Alt text of the screenshot. With `href` this is also the link's accessible name. */
+		alt?: string;
+		/**
+		 * Intrinsic pixel width of the screenshot (the `<img width>` attribute, so the
+		 * browser reserves space before the image loads). This does NOT size the frame —
+		 * size the frame with `class` (e.g. `w-64`).
+		 */
+		width?: number | string;
+		/** Intrinsic pixel height of the screenshot (see `width`). */
+		height?: number | string;
+		/** `<img srcset>` pass-through, for 1×/2× screenshots. */
+		srcset?: string;
+		/** `<img sizes>` pass-through. */
+		sizes?: string;
+		/** Image loading. `lazy` by default; use `eager` for a hero (above-the-fold) screenshot. */
+		loading?: "lazy" | "eager";
+		/** `<img fetchpriority>` pass-through. `high` for the LCP screenshot. */
+		fetchpriority?: "high" | "low" | "auto";
+		/**
+		 * Custom screen content (an iframe, a live component, a video...). Takes precedence
+		 * over `src`. The screen clips it and fixes its size; make the content fill it
+		 * (`w-full h-full`).
+		 */
+		children?: Snippet;
+		/** Makes the whole frame a link: renders `<a>` instead of `<div>`. */
+		href?: string;
+		/** Link target (e.g. `"_blank"`). Only relevant when `href` is set. */
+		target?: string;
+		/** Link `rel`. Defaults to `"noopener"` when `target` is `"_blank"`. */
+		rel?: string;
+		/**
+		 * Screen aspect ratio as a CSS `aspect-ratio` value (`"390 / 844"`, `390 / 844`,
+		 * `0.46`). Defaults to the `--stuic-phone-frame-screen-aspect-ratio` token
+		 * (`390 / 844`, an iPhone 14 class screen in CSS px). Ignored while `screenHeight`
+		 * is set.
+		 */
+		aspectRatio?: string | number;
+		/**
+		 * Fixed screen height (any CSS length). The screen becomes a window of that height
+		 * showing the TOP of the content, the rest is clipped and the aspect ratio no
+		 * longer applies. For a responsive version (clipped on narrow screens, whole phone
+		 * from a breakpoint up) set the `--stuic-phone-frame-screen-height` token through
+		 * `class` instead — see the README.
+		 */
+		screenHeight?: string;
+		/** Camera cutout drawn over the top of the screen. `none` by default. */
+		notch?: PhoneFrameNotch;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes for the frame (the bezel). Size the frame here. */
+		class?: string;
+		/** Additional CSS classes for the screen (the clipping window inside the bezel). */
+		classScreen?: string;
+		/** Additional CSS classes for the `<img>`. */
+		classImage?: string;
+		/** Bindable element reference (the `<div>` or `<a>`). */
+		el?: HTMLElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+
+	let {
+		src,
+		alt = "",
+		width,
+		height,
+		srcset,
+		sizes,
+		loading = "lazy",
+		fetchpriority,
+		children,
+		href,
+		target,
+		rel,
+		aspectRatio,
+		screenHeight,
+		notch = "none",
+		unstyled = false,
+		class: classProp,
+		classScreen: classScreenProp,
+		classImage: classImageProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-phone-frame", classProp));
+	let _classScreen = $derived(
+		unstyled ? classScreenProp : twMerge("stuic-phone-frame-screen", classScreenProp)
+	);
+	let _classImage = $derived(
+		unstyled ? classImageProp : twMerge("stuic-phone-frame-image", classImageProp)
+	);
+
+	// Prop-driven tokens go on the screen itself (closest to where they are read), so
+	// `style` from rest props stays untouched on the root.
+	let _screenStyle = $derived.by(() => {
+		const styles: string[] = [];
+		if (aspectRatio !== undefined && aspectRatio !== "") {
+			styles.push(`--stuic-phone-frame-screen-aspect-ratio: ${aspectRatio}`);
+		}
+		if (screenHeight) styles.push(`--stuic-phone-frame-screen-height: ${screenHeight}`);
+		return styles.length ? styles.join("; ") : undefined;
+	});
+
+	let _notch = $derived(!unstyled && notch !== "none" ? notch : undefined);
+
+	let _rel = $derived(rel ?? (target === "_blank" ? "noopener" : undefined));
+</script>
+
+{#snippet screen()}
+	<div class={_classScreen} style={_screenStyle}>
+		{#if children}
+			{@render children()}
+		{:else if src}
+			<img
+				{src}
+				{alt}
+				{width}
+				{height}
+				{srcset}
+				{sizes}
+				{loading}
+				{fetchpriority}
+				decoding="async"
+				class={_classImage}
+			/>
+		{/if}
+		{#if _notch}
+			<div class="stuic-phone-frame-notch" aria-hidden="true"></div>
+		{/if}
+	</div>
+{/snippet}
+
+{#if href}
+	<a
+		bind:this={el}
+		{href}
+		{target}
+		rel={_rel}
+		class={_class}
+		data-notch={_notch}
+		{...rest}
+	>
+		{@render screen()}
+	</a>
+{:else}
+	<div bind:this={el} class={_class} data-notch={_notch} {...rest}>
+		{@render screen()}
+	</div>
+{/if}

package/dist/components/PhoneFrame/PhoneFrame.svelte.d.ts

@@ -0,0 +1,71 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+/** Camera cutout drawn over the top of the screen. */
+export type PhoneFrameNotch = "none" | "island" | "notch";
+export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children" | "class"> {
+    /**
+     * Screenshot URL. The image fills the screen (`object-fit: cover`, anchored to the
+     * top). Omit it and render your own content with `children` instead.
+     */
+    src?: string;
+    /** Alt text of the screenshot. With `href` this is also the link's accessible name. */
+    alt?: string;
+    /**
+     * Intrinsic pixel width of the screenshot (the `<img width>` attribute, so the
+     * browser reserves space before the image loads). This does NOT size the frame —
+     * size the frame with `class` (e.g. `w-64`).
+     */
+    width?: number | string;
+    /** Intrinsic pixel height of the screenshot (see `width`). */
+    height?: number | string;
+    /** `<img srcset>` pass-through, for 1×/2× screenshots. */
+    srcset?: string;
+    /** `<img sizes>` pass-through. */
+    sizes?: string;
+    /** Image loading. `lazy` by default; use `eager` for a hero (above-the-fold) screenshot. */
+    loading?: "lazy" | "eager";
+    /** `<img fetchpriority>` pass-through. `high` for the LCP screenshot. */
+    fetchpriority?: "high" | "low" | "auto";
+    /**
+     * Custom screen content (an iframe, a live component, a video...). Takes precedence
+     * over `src`. The screen clips it and fixes its size; make the content fill it
+     * (`w-full h-full`).
+     */
+    children?: Snippet;
+    /** Makes the whole frame a link: renders `<a>` instead of `<div>`. */
+    href?: string;
+    /** Link target (e.g. `"_blank"`). Only relevant when `href` is set. */
+    target?: string;
+    /** Link `rel`. Defaults to `"noopener"` when `target` is `"_blank"`. */
+    rel?: string;
+    /**
+     * Screen aspect ratio as a CSS `aspect-ratio` value (`"390 / 844"`, `390 / 844`,
+     * `0.46`). Defaults to the `--stuic-phone-frame-screen-aspect-ratio` token
+     * (`390 / 844`, an iPhone 14 class screen in CSS px). Ignored while `screenHeight`
+     * is set.
+     */
+    aspectRatio?: string | number;
+    /**
+     * Fixed screen height (any CSS length). The screen becomes a window of that height
+     * showing the TOP of the content, the rest is clipped and the aspect ratio no
+     * longer applies. For a responsive version (clipped on narrow screens, whole phone
+     * from a breakpoint up) set the `--stuic-phone-frame-screen-height` token through
+     * `class` instead — see the README.
+     */
+    screenHeight?: string;
+    /** Camera cutout drawn over the top of the screen. `none` by default. */
+    notch?: PhoneFrameNotch;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes for the frame (the bezel). Size the frame here. */
+    class?: string;
+    /** Additional CSS classes for the screen (the clipping window inside the bezel). */
+    classScreen?: string;
+    /** Additional CSS classes for the `<img>`. */
+    classImage?: string;
+    /** Bindable element reference (the `<div>` or `<a>`). */
+    el?: HTMLElement;
+}
+declare const PhoneFrame: import("svelte").Component<Props, {}, "el">;
+type PhoneFrame = ReturnType<typeof PhoneFrame>;
+export default PhoneFrame;

package/dist/components/PhoneFrame/README.md

@@ -0,0 +1,260 @@
+# PhoneFrame
+
+A phone-shaped bezel around a screenshot — the "picture of the product" on a landing page, a
+preview of a page you are about to publish, a device mockup in docs. The screen holds an `<img>`
+(`src`), or any content you render yourself (`children`: an iframe, a live component, a video).
+With `href` the whole frame is a link to the page it pictures.
+
+The frame is a block element and fills its container: **size it with `class`** (`w-64`,
+`max-w-xs mx-auto`, a grid column). The screen is locked to a phone aspect ratio (`390 / 844`,
+an iPhone 14 class screen in CSS px) and derives its height from the width, so the frame scales
+with its column. Set `screenHeight` to turn the screen into a fixed-height window that shows only
+the top of the content — what a visitor sees first — with the rest clipped.
+
+## Props
+
+| Prop            | Type                            | Default  | Description                                                                                                                        |
+| --------------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `src`           | `string`                        | -        | Screenshot URL. Fills the screen (`object-fit: cover`, anchored to the top)                                                        |
+| `alt`           | `string`                        | `""`     | Alt text of the screenshot. With `href` it is also the link's accessible name                                                      |
+| `width`         | `number \| string`              | -        | Intrinsic pixel width of the screenshot (`<img width>`, reserves space before load). Does **not** size the frame — use `class`     |
+| `height`        | `number \| string`              | -        | Intrinsic pixel height of the screenshot (`<img height>`)                                                                          |
+| `srcset`        | `string`                        | -        | `<img srcset>` pass-through (1×/2× screenshots)                                                                                    |
+| `sizes`         | `string`                        | -        | `<img sizes>` pass-through                                                                                                         |
+| `loading`       | `"lazy" \| "eager"`             | `"lazy"` | Image loading. `eager` for a hero (above-the-fold) screenshot                                                                      |
+| `fetchpriority` | `"high" \| "low" \| "auto"`     | -        | `<img fetchpriority>` pass-through. `high` for the LCP screenshot                                                                  |
+| `children`      | `Snippet`                       | -        | Custom screen content; takes precedence over `src`. Make it fill the screen (`w-full h-full`)                                      |
+| `href`          | `string`                        | -        | Makes the whole frame a link (`<a>` instead of `<div>`)                                                                            |
+| `target`        | `string`                        | -        | Link target (e.g. `"_blank"`). Only with `href`                                                                                    |
+| `rel`           | `string`                        | -        | Link `rel`. Defaults to `"noopener"` when `target` is `"_blank"`                                                                   |
+| `aspectRatio`   | `string \| number`              | token    | Screen aspect ratio, any CSS `aspect-ratio` value (`"390 / 844"`, `390 / 844`, `0.46`). Ignored while `screenHeight` is set        |
+| `screenHeight`  | `string`                        | -        | Fixed screen height (CSS length): a window showing the top of the content, the rest clipped, the ratio dropped. See Clipped window |
+| `notch`         | `"none" \| "island" \| "notch"` | `"none"` | Camera cutout drawn over the top of the screen                                                                                     |
+| `unstyled`      | `boolean`                       | `false`  | Skip all default styling                                                                                                           |
+| `class`         | `string`                        | -        | Classes for the frame (the bezel). Size the frame here                                                                             |
+| `classScreen`   | `string`                        | -        | Classes for the screen (the clipping window inside the bezel)                                                                      |
+| `classImage`    | `string`                        | -        | Classes for the `<img>`                                                                                                            |
+| `el`            | `HTMLElement`                   | -        | Bindable element reference (the `<div>` or `<a>`)                                                                                  |
+
+Other attributes (`style`, `title`, `aria-*`, `data-*`, `onclick`, …) are spread onto the frame
+element.
+
+## Usage
+
+### A screenshot
+
+```svelte
+<script lang="ts">
+	import { PhoneFrame } from "@marianmeres/stuic";
+</script>
+
+<PhoneFrame
+	class="w-64"
+	src="/examples/apartment-page.webp"
+	alt="The apartment's page on a phone: Wi-Fi name and password, the key box code"
+	width={780}
+	height={1688}
+/>
+```
+
+Take the screenshot at the screen's CSS size (390×844) on a 2× display and pass the file's pixel
+size as `width`/`height`. With `object-fit: cover` a screenshot of a different ratio still fills the
+screen; the top stays visible and the bottom is cropped.
+
+### A link to the live page
+
+```svelte
+<PhoneFrame
+	class="w-64"
+	src="/examples/apartment-page.webp"
+	alt="Open the live apartment page"
+	width={780}
+	height={1688}
+	href="/i/abc123"
+	target="_blank"
+/>
+```
+
+`target="_blank"` gets `rel="noopener"` unless you pass `rel` yourself. The `alt` is the link's
+name — write it as the action, not as a picture description.
+
+### The hero screenshot (LCP)
+
+Everything below the fold stays lazy; the one in the hero should not:
+
+```svelte
+<PhoneFrame
+	class="w-72"
+	{src}
+	{alt}
+	{width}
+	{height}
+	loading="eager"
+	fetchpriority="high"
+/>
+```
+
+### Clipped window: the first screen only
+
+On a narrow viewport a whole phone is a tall picture of mostly scrolled-away content. Show the
+top rows at a fixed height instead:
+
+```svelte
+<PhoneFrame class="w-64" {src} {alt} {width} {height} screenHeight="20rem" />
+```
+
+For the common responsive version — clipped on narrow screens, the whole phone from a breakpoint
+up — set the token through `class` (it is inherited by the screen) and leave `screenHeight` unset:
+
+```svelte
+<PhoneFrame
+	class="w-full lg:w-72 [--stuic-phone-frame-screen-height:20rem] lg:[--stuic-phone-frame-screen-height:auto]"
+	{src}
+	{alt}
+	{width}
+	{height}
+/>
+```
+
+Don't combine the two: the `screenHeight` prop is an inline declaration on the screen and beats
+an inherited token at every breakpoint.
+
+### Phone cut off by the section edge
+
+The other hero pattern — a phone emerging from the bottom of the section — needs no component
+support. Clip the frame with your own wrapper:
+
+```svelte
+<div class="max-h-80 overflow-hidden">
+	<PhoneFrame class="w-72" {src} {alt} {width} {height} />
+</div>
+```
+
+### Camera cutout
+
+```svelte
+<PhoneFrame class="w-64" {src} {alt} notch="island" />
+<PhoneFrame class="w-64" {src} {alt} notch="notch" />
+```
+
+The cutout is painted over the screen content in the bezel color, so a screenshot taken in a plain
+browser window (no status bar) gets its top few pixels covered. It is `pointer-events: none` and
+`aria-hidden`.
+
+### Your own screen content
+
+```svelte
+<PhoneFrame class="w-72">
+	<iframe src="/preview" title="Live preview" class="w-full h-full border-0"></iframe>
+</PhoneFrame>
+
+<PhoneFrame class="w-72" notch="island">
+	<div class="w-full h-full overflow-y-auto bg-white p-4 pt-10">
+		<!-- a live component tree -->
+	</div>
+</PhoneFrame>
+```
+
+The screen clips (`overflow: hidden`) and has a definite height, so `h-full` on the content
+works. Scrolling content needs its own `overflow-y-auto`.
+
+### Another device ratio
+
+```svelte
+<!-- a tablet: 3:4 screen, bigger bezel radius -->
+<PhoneFrame
+	class="w-96"
+	aspectRatio="3 / 4"
+	style="--stuic-phone-frame-radius: 1.25rem; --stuic-phone-frame-padding: 0.75rem;"
+	{src}
+	{alt}
+/>
+```
+
+### Unstyled
+
+```svelte
+<PhoneFrame
+	unstyled
+	class="rounded-3xl bg-zinc-800 p-3"
+	classScreen="aspect-[9/19.5] overflow-hidden rounded-2xl"
+	classImage="h-full w-full object-cover"
+	{src}
+	{alt}
+/>
+```
+
+`unstyled` drops every `stuic-phone-frame*` class and the cutout; the three class props are then
+the only styling.
+
+## CSS Variables
+
+### Component Tokens
+
+Override globally in `:root` or locally via the `style` prop:
+
+| Variable                                  | Default                    | Description                                                                                       |
+| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `--stuic-phone-frame-bg`                  | `#171717`                  | Bezel color                                                                                       |
+| `--stuic-phone-frame-padding`             | `0.5rem`                   | Bezel thickness                                                                                   |
+| `--stuic-phone-frame-radius`              | `1.75rem`                  | Bezel (outer) corner radius                                                                       |
+| `--stuic-phone-frame-border-width`        | `--stuic-border-width`     | Hairline around the bezel (fallback: the shared border-width tier)                                |
+| `--stuic-phone-frame-border-color`        | `rgb(0 0 0 / 0.4)`         | Hairline color (`rgb(255 255 255 / 0.15)` in dark mode)                                           |
+| `--stuic-phone-frame-shadow`              | `--stuic-shadow-dialog`    | Drop shadow (fallback: the shared dialog shadow tier)                                             |
+| `--stuic-phone-frame-screen-bg`           | `--stuic-color-background` | Screen color, visible before the image loads or behind letterboxed content                        |
+| `--stuic-phone-frame-screen-radius`       | concentric                 | Screen corner radius. Default: bezel radius − padding − border width                              |
+| `--stuic-phone-frame-screen-aspect-ratio` | `390 / 844`                | Screen ratio while the height is `auto`. The `aspectRatio` prop sets it inline                    |
+| `--stuic-phone-frame-screen-height`       | `auto`                     | A length makes the screen a clipped window of that height. The `screenHeight` prop sets it inline |
+| `--stuic-phone-frame-island-width`        | `32%`                      | Dynamic-island width, relative to the screen width (the height follows, 126:37)                   |
+| `--stuic-phone-frame-island-top`          | `3%`                       | Dynamic-island offset from the top. A `%` is relative to the screen **width** (it is a margin)    |
+| `--stuic-phone-frame-notch-width`         | `54%`                      | Classic notch width, relative to the screen width (the height follows, 209:30)                    |
+| `--stuic-phone-frame-notch-radius`        | `1rem`                     | Classic notch bottom corner radius                                                                |
+| `--stuic-phone-frame-notch-bg`            | `--stuic-phone-frame-bg`   | Cutout color (both variants)                                                                      |
+| `--stuic-phone-frame-ring-width`          | `3px`                      | Focus ring width (linked frames, `:focus-visible`)                                                |
+| `--stuic-phone-frame-ring-offset`         | `2px`                      | Focus ring offset                                                                                 |
+| `--stuic-phone-frame-ring-color`          | `--stuic-color-ring`       | Focus ring color                                                                                  |
+
+The radius, border width and shadow intentionally do **not** follow `--stuic-radius-container`:
+a device bezel is a hardware shape, not UI chrome. The hairline and shadow do follow the shared
+tiers, so a flat theme (`--stuic-border-width: 0; --stuic-shadow-dialog: none`) flattens the phone
+too.
+
+### Customization Examples
+
+```css
+/* Global — a light "silver" phone */
+:root {
+	--stuic-phone-frame-bg: #e5e5e5;
+	--stuic-phone-frame-border-color: rgb(0 0 0 / 0.15);
+}
+
+/* Global — thicker bezel, keeps the screen corners concentric */
+:root {
+	--stuic-phone-frame-padding: 0.75rem;
+	--stuic-phone-frame-radius: 2.25rem;
+}
+```
+
+```svelte
+<!-- Local — no shadow, flat corners -->
+<PhoneFrame
+	style="--stuic-phone-frame-shadow: none; --stuic-phone-frame-radius: 0.5rem;"
+	{src}
+	{alt}
+/>
+```
+
+## Accessibility
+
+- With `href` the frame is a link whose accessible name is the image's `alt` (or your
+  `children`'s text). Give it one: an empty `alt` on a linked frame is an unnamed link.
+- Without `href` the frame is a plain container; the image is the only content a screen reader
+  sees, so a decorative screenshot can keep the default empty `alt`.
+- The camera cutout is `aria-hidden` and ignores pointer events.
+- Linked frames show a focus ring on `:focus-visible` (`--stuic-phone-frame-ring-*`).
+
+## Theming
+
+Only the screen background (`--stuic-color-background`) and the focus ring (`--stuic-color-ring`)
+come from the theme; the bezel is a fixed near-black in both schemes, with a lighter hairline in
+dark mode so it keeps an edge against dark page backgrounds.

package/dist/components/PhoneFrame/index.css

@@ -0,0 +1,114 @@
+/* ============================================================================
+   PHONE FRAME COMPONENT TOKENS
+   Override globally: :root { --stuic-phone-frame-bg: #e5e5e5; }
+   Override locally:  <PhoneFrame style="--stuic-phone-frame-padding: 0.75rem;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	/* Bezel */
+	--stuic-phone-frame-bg: #171717;
+	--stuic-phone-frame-padding: 0.5rem;
+	--stuic-phone-frame-radius: 1.75rem;
+	--stuic-phone-frame-border-color: rgb(0 0 0 / 0.4);
+
+	/* Screen */
+	--stuic-phone-frame-screen-bg: var(--stuic-color-background);
+	--stuic-phone-frame-screen-aspect-ratio: 390 / 844; /* iPhone 14 class, CSS px */
+	--stuic-phone-frame-screen-height: auto;            /* a length = clipped window */
+
+	/* Dynamic-island cutout (notch="island"); sizes relative to the screen width */
+	--stuic-phone-frame-island-width: 32%;
+	--stuic-phone-frame-island-top: 3%;
+
+	/* Classic notch cutout (notch="notch"); sizes relative to the screen width */
+	--stuic-phone-frame-notch-width: 54%;
+	--stuic-phone-frame-notch-radius: 1rem;
+
+	/* Focus ring (linked frames) */
+	--stuic-phone-frame-ring-width: 3px;
+	--stuic-phone-frame-ring-offset: 2px;
+	--stuic-phone-frame-ring-color: var(--stuic-color-ring);
+}
+
+:root.dark {
+	--stuic-phone-frame-border-color: rgb(255 255 255 / 0.15);
+}
+
+@layer components {
+	/* The bezel. Block-level so it fills its container: size it with `class`. */
+	.stuic-phone-frame {
+		display: block;
+		box-sizing: border-box;
+		padding: var(--stuic-phone-frame-padding);
+		background: var(--stuic-phone-frame-bg);
+		border-style: solid;
+		border-width: var(--stuic-phone-frame-border-width, var(--stuic-border-width));
+		border-color: var(--stuic-phone-frame-border-color);
+		border-radius: var(--stuic-phone-frame-radius);
+		box-shadow: var(--stuic-phone-frame-shadow, var(--stuic-shadow-dialog));
+		color: inherit;
+		text-decoration: none;
+	}
+
+	a.stuic-phone-frame:focus-visible {
+		outline: var(--stuic-phone-frame-ring-width) solid var(--stuic-phone-frame-ring-color);
+		outline-offset: var(--stuic-phone-frame-ring-offset);
+	}
+
+	/* The screen: a clipping window. `width: 100%` + `height: auto` lets `aspect-ratio`
+	   derive the height; a length in --stuic-phone-frame-screen-height makes both axes
+	   definite, so `aspect-ratio` is ignored and the window shows the top of the content
+	   (see RATIO_LOCKED_FRAME.md, G14). The radius is concentric with the bezel's unless
+	   overridden. */
+	.stuic-phone-frame-screen {
+		position: relative;
+		width: 100%;
+		height: var(--stuic-phone-frame-screen-height);
+		aspect-ratio: var(--stuic-phone-frame-screen-aspect-ratio);
+		overflow: hidden;
+		border-radius: var(
+			--stuic-phone-frame-screen-radius,
+			calc(
+				var(--stuic-phone-frame-radius) - var(--stuic-phone-frame-padding) -
+					var(--stuic-phone-frame-border-width, var(--stuic-border-width))
+			)
+		);
+		background: var(--stuic-phone-frame-screen-bg);
+	}
+
+	.stuic-phone-frame-image {
+		display: block;
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+		object-position: top;
+	}
+
+	/* Camera cutout, overlaid on the screen content. Width-relative so it keeps its
+	   shape in a clipped (fixed-height) screen too: the height comes from aspect-ratio,
+	   and the island's top offset is a margin (a % margin resolves against the
+	   containing block's WIDTH, even vertically). */
+	.stuic-phone-frame-notch {
+		position: absolute;
+		top: 0;
+		left: 50%;
+		transform: translateX(-50%);
+		pointer-events: none;
+		background: var(--stuic-phone-frame-notch-bg, var(--stuic-phone-frame-bg));
+	}
+
+	.stuic-phone-frame[data-notch="island"] .stuic-phone-frame-notch {
+		width: var(--stuic-phone-frame-island-width);
+		aspect-ratio: 126 / 37;
+		margin-top: var(--stuic-phone-frame-island-top);
+		border-radius: 9999px;
+	}
+
+	.stuic-phone-frame[data-notch="notch"] .stuic-phone-frame-notch {
+		width: var(--stuic-phone-frame-notch-width);
+		aspect-ratio: 209 / 30;
+		border-radius: 0 0 var(--stuic-phone-frame-notch-radius)
+			var(--stuic-phone-frame-notch-radius);
+	}
+}

package/dist/components/PhoneFrame/index.d.ts

@@ -0,0 +1 @@
+export { default as PhoneFrame, type Props as PhoneFrameProps, type PhoneFrameNotch, } from "./PhoneFrame.svelte";

package/dist/components/PhoneFrame/index.js

@@ -0,0 +1 @@
+export { default as PhoneFrame, } from "./PhoneFrame.svelte";

package/dist/index.css

@@ -119,6 +119,7 @@ In practice:
 @import "./components/Notifications/index.css";
 @import "./components/OtpInput/index.css";
 @import "./components/Pagination/index.css";
+@import "./components/PhoneFrame/index.css";
 @import "./components/Pill/index.css";
 @import "./components/PricingTable/index.css";
 @import "./components/Progress/index.css";

package/dist/index.d.ts

@@ -75,6 +75,7 @@ export * from "./components/Nav/index.js";
 export * from "./components/Notifications/index.js";
 export * from "./components/OtpInput/index.js";
 export * from "./components/Pagination/index.js";
+export * from "./components/PhoneFrame/index.js";
 export * from "./components/Pill/index.js";
 export * from "./components/PricingTable/index.js";
 export * from "./components/Progress/index.js";

package/dist/index.js

@@ -81,6 +81,7 @@ export * from "./components/Nav/index.js";
 export * from "./components/Notifications/index.js";
 export * from "./components/OtpInput/index.js";
 export * from "./components/Pagination/index.js";
+export * from "./components/PhoneFrame/index.js";
 export * from "./components/Pill/index.js";
 export * from "./components/PricingTable/index.js";
 export * from "./components/Progress/index.js";

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-83 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+84 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -118,6 +118,7 @@
 | Tree                | Hierarchical tree view with keyboard nav and drag-and-drop                                           |
 | X                   | Styled close/multiply SVG icon                                                                       |
 | ImageCycler         | Auto-cycling image carousel with fade transitions and preloading                                     |
+| PhoneFrame          | Phone-shaped bezel around a screenshot (or any content): link, clipped top window, notch, tokens     |
 
 ### E-commerce
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.193.0",
+	"version": "3.194.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -172,13 +172,13 @@
 		"prettier": "^3.9.9",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.25",
-		"svelte": "^5.57.1",
+		"svelte": "^5.57.2",
 		"svelte-check": "^4.7.6",
 		"tailwindcss": "^4.3.3",
 		"tsx": "^4.23.15",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.71.0",
-		"vite": "^7.3.6",
+		"typescript-eslint": "^8.71.1",
+		"vite": "^7.3.7",
 		"vitest": "^4.1.11",
 		"vitest-browser-svelte": "^2.2.1"
 	},