@foldjs/svelte 0.1.0 → 0.2.0

package/README.md

@@ -1,25 +1,47 @@
-# fold.js
+# fold.js: foldable phone support for React, Vue, Svelte and the web
 
-**Make any web app foldable-ready.** Hinge-aware layouts for foldable phones — in React, Vue, Svelte, Solid, Angular… or plain HTML.
+[![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/)
 
-- 🪟 **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
+**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.
 
-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).
+### [▶ 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)
 
----
+```bash
+npx foldjs audit https://your-site.com   # how foldable-ready is your site? Score out of 100 + HTML report
+```
+
+![fold.js demo switching a web app between flat, book and tabletop postures on a simulated foldable phone](https://raw.githubusercontent.com/christophe77/foldjs/main/docs/demo.gif)
+
+## Why fold.js?
+
+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";
@@ -37,13 +59,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>
@@ -59,7 +83,7 @@ const fold = useFold(); // fold.value.posture
 </template>
 ```
 
-## Svelte
+### Svelte (and SvelteKit)
 
 ```svelte
 <script>
@@ -75,7 +99,7 @@ const fold = useFold(); // fold.value.posture
 <div use:foldWhen={"tabletop"}>Tabletop only</div>
 ```
 
-## Solid
+### Solid
 
 ```tsx
 import { createFold, twoPane } from "@foldjs/solid";
@@ -88,7 +112,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>
@@ -101,7 +125,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";
@@ -117,23 +141,86 @@ 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://your-site.com
+```
+
+```
+  64  Samsung Galaxy Z Fold · book      2 critical, 6 warnings
+  94  Samsung Galaxy Z Fold · tabletop  0 critical, 2 warnings
+  67  Google Pixel Fold · book          3 critical, 5 warnings
+  88  Google Pixel Fold · tabletop      2 critical, 0 warnings
+
+  Top issues
+  ● Form field is split by the hinge #searchInput
+  ● Button is split by the hinge header > button.cta
+
+  Foldable score: 78/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` or `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 |
+| `--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.
 
 ## Core API
 
 ```ts
-import { getFold, subscribe, simulate, twoPaneLayout, bindTwoPane } from "foldjs";
+import { getFold, subscribe, simulate, twoPaneLayout, bindTwoPane, findHingeCollisions, foldScore } from "foldjs";
 
 getFold();
 // {
@@ -148,28 +235,63 @@ 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.
+
+### 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
@@ -178,6 +300,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.d.cts

@@ -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

@@ -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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@foldjs/svelte",
-  "version": "0.1.0",
-  "description": "Svelte bindings for Fold.js: a `fold` store and `use:twoPane` / `use:foldWhen` actions.",
+  "version": "0.2.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": {
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/christophe77/foldjs.git",
     "directory": "packages/svelte"
   },
-  "homepage": "https://github.com/christophe77/foldjs#readme",
+  "homepage": "https://christophe77.github.io/foldjs/",
   "bugs": "https://github.com/christophe77/foldjs/issues",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,14 +28,30 @@
   ],
   "sideEffects": false,
   "keywords": [
-    "foldable",
     "svelte",
+    "sveltejs",
+    "sveltekit",
+    "svelte-action",
+    "store",
+    "foldable",
+    "foldable-phone",
+    "foldables",
     "dual-screen",
     "hinge",
+    "viewport-segments",
+    "device-posture",
+    "galaxy-fold",
+    "pixel-fold",
+    "surface-duo",
+    "two-pane",
+    "responsive",
+    "responsive-design",
+    "layout",
+    "tabletop-mode",
     "foldjs"
   ],
   "peerDependencies": {
-    "foldjs": "^0.1.0",
+    "foldjs": "^0.2.0",
     "svelte": ">=4"
   },
   "scripts": {