@foldjs/svelte 0.1.1 → 0.3.0

package/README.md

@@ -1,33 +1,49 @@
-# fold.js
+# fold.js: foldable phone support for React, Vue, Svelte and the web
 
 [![npm](https://img.shields.io/npm/v/foldjs?color=5b4bff)](https://www.npmjs.com/package/foldjs)
 [![gzip size](https://img.shields.io/bundlejs/size/foldjs?label=gzip)](https://bundlejs.com/?q=foldjs)
 [![license](https://img.shields.io/npm/l/foldjs)](LICENSE)
+[![demo](https://img.shields.io/badge/demo-live-5b4bff)](https://christophe77.github.io/foldjs/)
 
-**Make any web app foldable-ready.** Hinge-aware layouts for foldable phones — in React, Vue, Svelte, Solid, Angular… or plain HTML.
+**fold.js is an open-source JavaScript library that makes web apps work properly on foldable phones** such as the Samsung Galaxy Z Fold, Google Pixel Fold, Honor Magic V or Microsoft Surface Duo. It detects the hinge and the device posture (flat, book, tabletop), and gives you two-pane layouts that never put content under the hinge. It works with React, Vue, Svelte, Solid, Angular, Astro or plain HTML, weighs about 2 kB, and ships with a built-in foldable simulator so you can build without owning a device.
 
-### [▶ Live demo](https://christophe77.github.io/foldjs/) — no foldable needed, the simulator is built in.
+> 📊 **New study:** [94% of popular websites split a button across a foldable's hinge](https://christophe77.github.io/foldjs/study.html) (79 sites audited on a Galaxy Z Fold, including Google, Amazon and Facebook, plus a run at the leaked iPhone Fold size: 88%).
 
-![fold.js switching between flat, book and tabletop postures](https://raw.githubusercontent.com/christophe77/foldjs/main/docs/demo.gif)
+### [▶ Try the live demo](https://christophe77.github.io/foldjs/) (works on desktop: the simulator is built in) · [See an existing site fixed in one line](https://christophe77.github.io/foldjs/legacy.html)
 
-- 🪟 **Two-pane layouts** that put each pane on its own side of the hinge
-- 📐 **Posture detection**: `flat`, `book`, `tabletop`, `folded`
-- 🧪 **Built-in foldable simulator** — no device, no DevTools setup
-- 🧩 **Works everywhere**: framework-agnostic core, thin adapters, Web Components, CSS-only layer
-- 🪶 **~2 kB** min+gzip core, zero dependencies, SSR-safe, TypeScript
+```bash
+npx foldjs audit https://your-site.com   # how foldable-ready is your site? Score out of 100 + HTML report
+```
+
+![fold.js demo: npx foldjs audit scores a mobile site 83/100, the HTML report outlines elements under the hinge, foldjs/auto fixes the site to 100/100, then a fold.js app switches between book and tabletop postures](https://raw.githubusercontent.com/christophe77/foldjs/main/docs/demo.gif)
+
+## Why fold.js?
 
-Built on the web standards shipping in Chromium: [CSS Viewport Segments](https://developer.mozilla.org/en-US/docs/Web/API/Viewport_segments_API) and the [Device Posture API](https://developer.mozilla.org/en-US/docs/Web/API/Device_Posture_API).
+Most web apps treat a foldable phone as one big rectangle. Once the device is folded or spanned, text and buttons land under the hinge, and the half-folded "tabletop" posture is ignored. Chromium now exposes the right web standards ([CSS Viewport Segments](https://developer.mozilla.org/en-US/docs/Web/API/Viewport_segments_API) and the [Device Posture API](https://developer.mozilla.org/en-US/docs/Web/API/Device_Posture_API)), but using them directly means pixel math, event wiring, SSR guards and no way to test without hardware. Microsoft's earlier dual-screen libraries (`react-foldable`, `react-native-dualscreen`) are archived.
 
----
+fold.js wraps all of that in one small, framework-agnostic API.
+
+## Features
+
+- 🪟 **Two-pane layouts**: each pane on its own side of the hinge, stacked (or one hidden) on regular phones
+- 📐 **Posture detection**: `flat`, `book` (vertical hinge), `tabletop` (horizontal hinge), `folded`
+- 📏 **Hinge geometry**: exact position and size of the hinge and of each screen segment, in JS and as CSS variables
+- 🧪 **Built-in foldable simulator**: switch postures from a floating panel or with Alt+Shift+F, on any desktop browser, with live outlines of everything under the hinge
+- 🔍 **Audit CLI**: `npx foldjs audit <url>` scores any site out of 100 on Galaxy Z Fold and Pixel Fold, with an HTML report, a README badge and a CI mode
+- 🪄 **foldjs/auto**: one script tag retrofits an existing mobile site (modals, tab bars, videos, text columns), no rewrite needed
+- 🧩 **Every framework**: React, Vue, Svelte, Solid adapters, Web Components for everything else, and a CSS-only layer
+- 🪶 **Tiny and safe**: about 2 kB min+gzip, zero dependencies, SSR-safe (Next.js, Nuxt, SvelteKit, Astro), TypeScript types included
 
 ## Install
 
 ```bash
-npm i foldjs            # core, CSS, Web Components, simulator
+npm i foldjs            # core, CSS layer, Web Components, simulator
 npm i @foldjs/react     # or @foldjs/vue, @foldjs/svelte, @foldjs/solid
 ```
 
-## React
+## Quick start
+
+### React (and Next.js)
 
 ```tsx
 import { TwoPane, FoldWhen, FoldDevtools, useFold } from "@foldjs/react";
@@ -45,13 +61,15 @@ export function Inbox() {
       <FoldWhen posture="tabletop">
         <PlayerControls />
       </FoldWhen>
-      {import.meta.env.DEV && <FoldDevtools initial="book" />}
+      {process.env.NODE_ENV === "development" && <FoldDevtools initial="book" />}
     </>
   );
 }
 ```
 
-## Vue
+`@foldjs/react` is marked `"use client"`, so it works in the Next.js App Router out of the box.
+
+### Vue (and Nuxt)
 
 ```vue
 <script setup>
@@ -67,7 +85,7 @@ const fold = useFold(); // fold.value.posture
 </template>
 ```
 
-## Svelte
+### Svelte (and SvelteKit)
 
 ```svelte
 <script>
@@ -83,7 +101,7 @@ const fold = useFold(); // fold.value.posture
 <div use:foldWhen={"tabletop"}>Tabletop only</div>
 ```
 
-## Solid
+### Solid
 
 ```tsx
 import { createFold, twoPane } from "@foldjs/solid";
@@ -96,7 +114,7 @@ const fold = createFold(); // fold().posture
 </div>
 ```
 
-## Web Components (Angular, Lit, Astro, htmx, plain HTML…)
+### Web Components (Angular, Lit, Astro, htmx, plain HTML)
 
 ```html
 <script type="module">import "foldjs/elements";</script>
@@ -109,7 +127,7 @@ const fold = createFold(); // fold().posture
 <fold-when posture="tabletop book">Only on a split screen</fold-when>
 ```
 
-## CSS only
+### CSS only
 
 ```js
 import "foldjs/css";
@@ -125,23 +143,103 @@ init(); // optional: enables the simulator and non-native browsers
 <div class="fold-only-tabletop">Tabletop only</div>
 ```
 
-Variables available on `<html>`: `--fold-hinge-x|y|width|height`, `--fold-segment-0-width|height`, `--fold-segment-1-width|height`.
-Attributes: `data-fold-posture`, `data-fold-spanning`.
+CSS variables on `<html>`: `--fold-hinge-x|y|width|height`, `--fold-segment-0-width|height`, `--fold-segment-1-width|height`.
+Attributes on `<html>`: `data-fold-posture`, `data-fold-spanning`.
 
-## The simulator
+## Test foldable layouts without a device
 
 ```js
 import { mountDevtools } from "foldjs/devtools";
 mountDevtools({ initial: "book", position: "bottom-right", hingeSize: 24 });
 ```
 
-Switch between **Device / Flat / Book / Tabletop** from the floating panel, or press **Alt + Shift + F**.
-Or drive it from code (tests, demos, Storybook): `simulate({ posture: "tabletop" })`, `simulate(null)`.
+A floating panel lets you switch between **Device / Flat / Book / Tabletop** and draws the simulated hinge on screen. Press **Alt + Shift + F** to cycle postures. In tests, demos or Storybook, drive it from code: `simulate({ posture: "tabletop" })`, then `simulate(null)` to go back to the real device.
+
+The panel also shows a live **foldable score** and outlines every element under the hinge: red for split buttons and form fields, orange for text, modals, fixed elements and videos, yellow for images. Click the score to toggle the outlines and log each issue, with a suggested fix, to the console. Pass `highlight: false` to turn it off.
+
+## Audit any website: `npx foldjs audit`
+
+```bash
+npx foldjs audit https://christophe77.github.io/foldjs/legacy.html
+```
+
+```
+  70  Samsung Galaxy Z Fold · book      2 critical, 6 warnings
+  94  Samsung Galaxy Z Fold · tabletop  0 critical, 2 warnings
+  70  Google Pixel Fold · book          2 critical, 6 warnings
+  97  Google Pixel Fold · tabletop      0 critical, 1 warnings
+
+  Top issues
+  ● Button is split by the hinge #book
+  ● Link is split by the hinge nav.bottom-nav > a:nth-of-type(3)
+  ● Text crosses the hinge main > article > p:nth-of-type(1)
+
+  Foldable score: 83/100
+  Report: ./foldjs-report/report.html
+```
+
+It opens the page in headless Chrome at the real inner-screen sizes of the Samsung Galaxy Z Fold and Google Pixel Fold, in book and tabletop postures, and lists every element under the hinge. The HTML report shows annotated screenshots and a fix for each issue, plus a badge for your README: [![foldable-ready](https://img.shields.io/badge/foldable--ready-100%2F100-brightgreen)](https://github.com/christophe77/foldjs)
+
+| Option | Default | |
+|---|---|---|
+| `--device` | `all` | `galaxy-z-fold`, `pixel-fold`, `iphone-fold` or `all`. `iphone-fold` uses leaked specs (904×640 CSS px, iPhone user agent) and is not part of `all`. |
+| `--posture` | `all` | `book`, `tabletop` or `all` |
+| `--out` | `foldjs-report` | Report folder (`report.html` + `report.json`) |
+| `--min-score` | | Exit with code 1 below this score, for CI |
+| `--dismiss-consent` | | Close cookie banners (rejecting when possible) before the audit |
+| `--json` | | Print the result as JSON |
+| `--browser` | auto | Chrome, Edge or Chromium path (or `CHROME_PATH`). No browser is downloaded. |
+
+In CI (GitHub Actions runners ship with Chrome):
+
+```yaml
+- run: npx foldjs audit http://localhost:3000 --min-score 90
+```
+
+The audit checks the first screen of the page. It runs `findHingeCollisions()` from the core, so you can also call it yourself in a browser or in Playwright tests.
+
+## Retrofit an existing site: `foldjs/auto`
+
+One line, no build step, no rewrite:
+
+```html
+<script src="https://unpkg.com/foldjs/dist/auto.global.js"></script>
+```
+
+Or from your bundle: `import { autoFix } from "foldjs/auto"; const undo = autoFix();`
+
+On a foldable (and in the simulator), it applies safe, reversible fixes as inline styles, and removes them as soon as the device is flat again:
+
+| Fix | Automatic | Option |
+|---|---|---|
+| Open dialogs and modals move to a single screen (right screen in book, top half in tabletop) | ✅ | `modals` |
+| Fixed tab bars and toolbars get an empty slot under the hinge, so no item is split | ✅ | `bars` |
+| Videos and iframes stay on one screen (top half in tabletop) | ✅ | `media` |
+| Text blocks flow into two columns around the hinge | add `data-fold-columns` | `columns` |
+| Any element is pushed off the hinge (titles, call-to-action buttons) | add `data-fold-avoid` | `avoid` |
+| An element and its children are never touched | add `data-fold-ignore` | |
+
+Turn a fix off with `autoFix({ bars: false })` or `<script src="…/auto.global.js" data-bars="false">`. [See it on a typical mobile site](https://christophe77.github.io/foldjs/legacy.html): the foldable score goes from 70 to 100 in book posture.
+
+## iPhone Fold: the virtual fold
+
+Safari does not implement the foldable web APIs, so a page cannot know where the iPhone Fold folds. fold.js handles it anyway: when an Apple touch screen measures 600 to 720px on its short side (regular iPhones are under 450px, iPads at least 744px, so only an unfolded iPhone Fold fits) and is held in landscape, it splits the viewport at its center line. `<TwoPane>`, `use:twoPane`, `<fold-two-pane>` and the CSS layer then show list and detail side by side, like on an iPad. In portrait, nothing changes.
+
+It is on by default and only affects that case. `getFold().virtual` tells you when it is active. Change it with `configure()`:
+
+```js
+import { configure } from "foldjs"; // also exported by every adapter
+configure({ virtualFold: "auto" }); // default: unfolded iPhone Fold only
+configure({ virtualFold: true });   // any landscape screen at least 600px tall (tablets, desktop testing)
+configure({ virtualFold: false });  // never
+```
+
+The iPhone Fold crease is reportedly much shallower than on earlier foldables, so content on the fold stays readable. The virtual fold is about using the wide inner screen well, not about hiding a gap. Preview it in the [demo](https://christophe77.github.io/foldjs/?virtual=1), and audit a site at the leaked iPhone Fold size with `npx foldjs audit <url> --device iphone-fold`.
 
 ## Core API
 
 ```ts
-import { getFold, subscribe, simulate, twoPaneLayout, bindTwoPane } from "foldjs";
+import { getFold, subscribe, simulate, twoPaneLayout, bindTwoPane, findHingeCollisions, foldScore } from "foldjs";
 
 getFold();
 // {
@@ -156,28 +254,66 @@ getFold();
 // }
 
 const off = subscribe((state) => console.log(state.posture));
+
+// What sits under the hinge right now (real or simulated)?
+const issues = findHingeCollisions(); // [{ severity, kind, message, suggestion, selector, rect, element }, …]
+foldScore(issues);                    // 0 to 100
 ```
 
-Writing an adapter for another framework? `subscribe` + `getFold` are all you need; `twoPaneLayout(state)` returns the styles every built-in adapter uses.
+Writing an adapter for another framework? `subscribe` and `getFold` are all you need, and `twoPaneLayout(state)` returns the styles every built-in adapter uses.
+
+## FAQ
+
+### How do I check if my website works on foldable phones?
+Run `npx foldjs audit https://your-site.com`. It tests the page on the Samsung Galaxy Z Fold and Google Pixel Fold in book and tabletop postures, gives a score out of 100 and an HTML report with screenshots of every element under the hinge. While developing, the fold.js simulator shows the same issues live.
+
+### Can I make an existing mobile site foldable-friendly without rewriting it?
+Yes. Add `<script src="https://unpkg.com/foldjs/dist/auto.global.js"></script>`. It moves modals, tab bars and videos off the hinge automatically, and you can mark text blocks with `data-fold-columns` or elements with `data-fold-avoid` for more. For new screens, `<TwoPane>` gives the best result.
+
+### How do I detect a foldable phone in JavaScript?
+Call `getFold()` from `foldjs` (or `useFold()` in React and Vue). `isSpanned` tells you whether the viewport is split by a hinge, `posture` tells you how the device is held, and `hinge` gives the hinge rectangle in CSS pixels. Under the hood fold.js reads `window.viewport.segments` and `navigator.devicePosture`, with a fallback for older Edge builds.
+
+### How do I keep content away from the hinge in CSS?
+Use the `fold-two-pane` class from `foldjs/css`, or the `--fold-hinge-*` and `--fold-segment-*` variables. On supporting browsers the CSS layer also uses the native `env(viewport-segment-*)` values and the `horizontal-viewport-segments` / `vertical-viewport-segments` media queries.
+
+### What is the difference between book and tabletop posture?
+**Book** means the hinge is vertical and the two screens are side by side, like an open book: ideal for list and detail. **Tabletop** means the hinge is horizontal, like a half-open laptop: ideal for a video or camera on top and controls at the bottom.
+
+### Can I build for foldables without owning one?
+Yes. The built-in simulator (`<FoldDevtools />`, `<FoldDevtools>` in Vue, or `mountDevtools()` anywhere) fakes the segments and posture on any desktop browser. Chrome DevTools device emulation (Galaxy Z Fold, Surface Duo) also works with fold.js.
+
+### Does fold.js work on the iPhone Fold?
+Yes, with a virtual fold. Safari exposes no foldable API, so fold.js detects an unfolded iPhone Fold from its screen size and splits the viewport at its center in landscape. Two-pane layouts work out of the box; posture detection (book or tabletop angle) is not possible on iOS until WebKit ships the Device Posture and Viewport Segments APIs.
+
+### Which devices and browsers are supported?
+Chrome and Edge on Android foldables (Samsung Galaxy Z Fold, Google Pixel Fold, Honor, Oppo, Vivo, Surface Duo) support the native APIs. On every other browser, including Samsung Internet, Firefox and Safari on iOS, fold.js falls back to a normal single-screen layout and the simulator still works.
+
+### Does fold.js work with server-side rendering?
+Yes. On the server the state is a flat, unsplit screen, and it updates on the client after hydration. It works with Next.js, Nuxt, SvelteKit, Remix and Astro.
+
+### Is fold.js a replacement for react-foldable or react-native-dualscreen?
+For the web, yes. Those Microsoft packages are archived and rely on the deprecated `spanning` media query and `getWindowSegments()`. fold.js uses the current standards and supports more frameworks. It does not target React Native.
 
 ## Browser support
 
-| | Native | With `foldjs` |
+| | Native APIs | With fold.js |
 |---|---|---|
-| Chrome / Edge on Android foldables | ✅ Viewport Segments + Device Posture | ✅ |
-| Samsung Internet, other browsers | — | ✅ Single-screen fallback, simulator |
-| Desktop | — | ✅ Simulator |
+| Chrome / Edge on Android foldables | ✅ Viewport Segments + Device Posture | ✅ Full support |
+| Samsung Internet, Firefox, Safari | ❌ | ✅ Single-screen fallback, simulator |
+| Desktop browsers | ❌ | ✅ Simulator |
 
-## Repository
+## Packages
 
-```
-packages/core     foldjs           core, CSS, Web Components, simulator
-packages/react    @foldjs/react
-packages/vue      @foldjs/vue
-packages/svelte   @foldjs/svelte
-packages/solid    @foldjs/solid
-apps/demo         demo site (Vite + React)
-```
+| Package | Description |
+|---|---|
+| [`foldjs`](https://www.npmjs.com/package/foldjs) | Core API, CSS layer (`foldjs/css`), Web Components (`foldjs/elements`), simulator (`foldjs/devtools`), retrofit script (`foldjs/auto`) |
+| [`@foldjs/react`](https://www.npmjs.com/package/@foldjs/react) | `useFold`, `<TwoPane>`, `<FoldWhen>`, `<FoldDevtools>` |
+| [`@foldjs/vue`](https://www.npmjs.com/package/@foldjs/vue) | `useFold`, `<TwoPane>`, `<FoldWhen>`, `<FoldDevtools>` |
+| [`@foldjs/svelte`](https://www.npmjs.com/package/@foldjs/svelte) | `fold` store, `use:twoPane`, `use:foldWhen` |
+| [`@foldjs/solid`](https://www.npmjs.com/package/@foldjs/solid) | `createFold`, `use:twoPane` |
+| [`@foldjs/cli`](https://www.npmjs.com/package/@foldjs/cli) | `foldjs audit` command (run it with `npx foldjs audit`) |
+
+## Contributing
 
 ```bash
 npm install
@@ -186,6 +322,8 @@ npm test
 npm run build
 ```
 
+Issues and pull requests are welcome, especially reports from people testing on real foldable devices.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  configure: () => import_foldjs2.configure,
   fold: () => fold,
   foldWhen: () => foldWhen,
   mountDevtools: () => import_devtools.mountDevtools,
@@ -56,6 +57,7 @@ function foldWhen(node, posture) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  configure,
   fold,
   foldWhen,
   mountDevtools,

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Readable } from 'svelte/store';
 import { FoldState, Posture, TwoPaneOptions } from 'foldjs';
-export { FoldState, Posture, Rect, Spanning, simulate } from 'foldjs';
+export { FoldState, Posture, Rect, Spanning, configure, simulate } from 'foldjs';
 export { mountDevtools } from 'foldjs/devtools';
 
 /** Live foldable state: `$fold.posture`, `$fold.hinge`… */
@@ -15,7 +15,7 @@ declare function twoPane(node: HTMLElement, options?: TwoPaneOptions): {
     update(next?: TwoPaneOptions): void;
     destroy: () => void;
 };
-/** <div use:foldWhen={"tabletop"}>…</div> — hidden unless the posture matches. */
+/** <div use:foldWhen={"tabletop"}>…</div>: hidden unless the posture matches. */
 declare function foldWhen(node: HTMLElement, posture: Posture | Posture[]): {
     update(next: Posture | Posture[]): void;
     destroy: () => void;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Readable } from 'svelte/store';
 import { FoldState, Posture, TwoPaneOptions } from 'foldjs';
-export { FoldState, Posture, Rect, Spanning, simulate } from 'foldjs';
+export { FoldState, Posture, Rect, Spanning, configure, simulate } from 'foldjs';
 export { mountDevtools } from 'foldjs/devtools';
 
 /** Live foldable state: `$fold.posture`, `$fold.hinge`… */
@@ -15,7 +15,7 @@ declare function twoPane(node: HTMLElement, options?: TwoPaneOptions): {
     update(next?: TwoPaneOptions): void;
     destroy: () => void;
 };
-/** <div use:foldWhen={"tabletop"}>…</div> — hidden unless the posture matches. */
+/** <div use:foldWhen={"tabletop"}>…</div>: hidden unless the posture matches. */
 declare function foldWhen(node: HTMLElement, posture: Posture | Posture[]): {
     update(next: Posture | Posture[]): void;
     destroy: () => void;

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { readable } from "svelte/store";
 import { bindTwoPane, getFold, subscribe } from "foldjs";
-import { simulate } from "foldjs";
+import { configure, simulate } from "foldjs";
 import { mountDevtools } from "foldjs/devtools";
 var fold = readable(getFold(), (set) => {
   set(getFold());
@@ -27,6 +27,7 @@ function foldWhen(node, posture) {
   };
 }
 export {
+  configure,
   fold,
   foldWhen,
   mountDevtools,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@foldjs/svelte",
-  "version": "0.1.1",
-  "description": "Svelte bindings for Fold.js: a `fold` store and `use:twoPane` / `use:foldWhen` actions.",
+  "version": "0.3.0",
+  "description": "Svelte store and actions for foldable phones: $fold, use:twoPane, use:foldWhen and a built-in foldable simulator. Works with SvelteKit.",
   "license": "MIT",
   "author": "christophe77",
   "repository": {
@@ -28,14 +28,31 @@
   ],
   "sideEffects": false,
   "keywords": [
-    "foldable",
     "svelte",
+    "sveltejs",
+    "sveltekit",
+    "svelte-action",
+    "store",
+    "foldable",
+    "foldable-phone",
+    "foldables",
     "dual-screen",
     "hinge",
-    "foldjs"
+    "viewport-segments",
+    "device-posture",
+    "galaxy-fold",
+    "pixel-fold",
+    "surface-duo",
+    "two-pane",
+    "responsive",
+    "responsive-design",
+    "layout",
+    "tabletop-mode",
+    "foldjs",
+    "iphone-fold"
   ],
   "peerDependencies": {
-    "foldjs": "^0.1.0",
+    "foldjs": "^0.3.0",
     "svelte": ">=4"
   },
   "scripts": {