@synopackageland/ui 0.4.0

package/docs/app-local-modal.md

@@ -0,0 +1,120 @@
+# App-local modal
+
+Status: implemented for 0.4.0 (unreleased). The public API approved for U4 is
+`AppRoot modal-scope="app"`; the default remains `"document"`.
+
+```vue
+<AppRoot modal-scope="app" style="width: 480px; height: 500px">
+  <Dialog v-model:open="open" title="Settings" description="Package settings" />
+  <Sheet v-model:open="details" title="Details" description="Details" />
+</AppRoot>
+```
+
+Give each independent Vue app a unique `app.config.idPrefix` before mounting.
+Supply a bounded root size and import the embedded theme inside DSM. The root
+creates a scrollable background wrapper and a sibling portal host. Dialog,
+Sheet and supported popup primitives inherit the root mode; there are no
+per-dialog scope overrides. Select the mode at mount time and remount to change
+it. Nesting an app-local AppRoot and simultaneous app/document overlays throw explicit
+errors; a rejected overlay must be closed/unmounted by the app's error handler.
+
+## Behavior and accessibility
+
+| Concern | Default document mode | App mode |
+| --- | --- | --- |
+| Pointer | Original Reka document stack and body lock. | Inert only this root's background and lower local modal layers; other roots/host remain interactive. |
+| Scroll | Shared body scroll lock and compensation policy. | Lock the background wrapper, preserve its scroll position, and contain backdrop wheel/touch gestures locally. Active panels and host/other-app scrolling remain native. |
+| Accessibility | Original Reka hideOthers semantics. | Local inert/aria-hidden ownership; keep the active dialog and registered popup branches accessible. Dialogs keep role, title and description references and omit aria-modal, since the rest of the page is available. |
+| Focus | Original document FocusScope coordination. | Loop Tab/Shift+Tab in the active local panel while focus belongs to it. Deliberate other-app/host transitions remain outside the local trap. |
+| Escape | Original document layer routing. | Route once to the focused root's top layer. IME composition is ignored and cancellation is preserved. Host/body events infer no local app. |
+| Cleanup | Shared Reka lock counts. | Restore locally owned inert/ARIA/style values only when still owned. Remove listeners/branches on unmount and never mutate body. |
+
+Opening from a focused trigger or an actual pointer activation moves focus into
+the panel. A programmatic open in an unfocused app does not steal another app's
+focus. Closing restores a connected local trigger only if focus still belongs
+to that app; disconnected triggers fall back to the remaining local panel/root.
+Nested panels retain the parent background lock, temporarily hide/inert the
+parent panel, and restore its interaction on close. Presence/exit animations
+retain layer ownership until Reka actually removes the layer.
+
+A host must provide an accessible window switch mechanism: a looping Tab
+sequence inside a local dialog does not itself reach another app. There is no
+claim of whole-document modality in app mode. VoiceOver/NVDA exposure and
+Safari/iOS gesture behavior still need manual acceptance.
+
+Dialog and Sheet forward cancellable `escapeKeyDown`, `pointerDownOutside`,
+`interactOutside`, `openAutoFocus`, and `closeAutoFocus` events. For example:
+
+```vue
+<Dialog title="Settings" @escape-key-down="event => event.preventDefault()" />
+```
+
+## Popup coverage
+
+Popover, Select, DropdownMenu, DatePicker (through Popover), SplitButton (through
+DropdownMenu), ContextMenu (through Menu), and Tooltip use the same patched
+DismissableLayer/focus boundary. Portal branches are part of the local stack;
+closing a child does not also close the parent. Tooltip-open coordination is
+local to the root. Toast portals/live announcements remain in the sibling
+portal host, outside the inert background. Raw Reka primitives from a separate
+consumer import are outside this contract.
+
+The wrapper is the registered background scroll container in this version.
+Scroll containers within it are blocked by inert/background containment while
+a local modal is present. Apps with their own external Teleports or desktop
+scrolling cannot claim independent containment. Keep custom portals inside the
+root and inside the active panel, or use the library's supported popup components.
+
+## Delivery and patch maintenance
+
+Reka 2.10.5 is an exact development dependency, bundled into the UI library's
+ESM dist. It is no longer a consumer runtime dependency. Vue remains an external
+peer, and the bundled code uses that same Vue instance. Existing consumers get
+the body-style fix on rebuilding with 0.4.0 without a package-manager patch or
+app code change. Independent modality is opt-in.
+
+`build/reka-patches.json` records the SHA-256 of every original upstream ESM
+module plus exact before/after hunks. `build/rekaPatch.ts` verifies the installed
+version and all input hashes before the build; each hunk must match exactly
+once. The Vite plugin loads patched modules in memory, never edits node_modules,
+and is also used by Vitest. Any source/hash/hunk mismatch fails the build.
+
+The body-scroll patch follows the U3 shared-lock candidate: save owned body
+padding-right, margin-right, overflow, pointer-events and root scrollbar-width
+values/priorities once on lock acquisition; restore once after the final release.
+The bundled DismissableLayer additionally preserves the original pointer-events
+priority. AppRoot-lifetime snapshots and body MutationObservers are not used.
+
+The library adds a private scope bridge to Reka's shared primitives rather than
+copying the full modal implementation. Default Reka rendering, Presence,
+component contexts, labels and keyboard navigation remain in use. The bridge
+bypasses document scroll locking, hideOthers, global layer stacks and global
+FocusScope/guards only when the app context is present.
+
+`dist/reka-runtime.json` records the patch manifest hash, source hashes and
+bundle hash. `pnpm check:package` verifies inventory, external imports, consumer
+dependency/declaration boundaries and the complete Reka MIT notice.
+`pnpm notices:update` / `pnpm notices:check` include the bundled runtime's graph.
+
+## Verification and limitations
+
+- Unit regressions cover interleaved body locks, important styles, repeated cycles,
+  unmount, local background ownership/external changes, mixed-mode rejection,
+  nested layers, focused-root Escape and unfocused programmatic opens.
+- `pnpm check:local-browser [output-dir] [existing-ego-space-id]` packs and installs
+  the UI in a clean consumer, verifies a single Vue/no external Reka dependency,
+  and uses native mouse/keyboard input in Chromium. It also runs the existing
+  default document-mode isolation fixture against that installed package.
+- The default document-wide pointer/ARIA policy remains intentional. Independent
+  apps without unique idPrefix still collide; this remains an executable expected
+  failure, not a promise of automatic ID assignment.
+- Simultaneous app/document overlays are rejected within this bundled runtime.
+  Separate UI versions, multiple Reka runtime copies or unrelated host modal
+  libraries cannot coordinate ownership through this private bridge. Do not mix
+  them; rebuilding all participating apps with one SDK version is recommended.
+- The default shared body lock still does not arbitrate unrelated libraries
+  changing its owned properties during a lock. Local ownership restoration does
+  preserve externally changed attribute/style values.
+- Evidence is bounded to Chromium in one document. Firefox, WebKit/iOS, iframe,
+  shadow-DOM focus paths and manual assistive-technology acceptance are unverified.
+  Do not infer DSM runtime certification or browser-wide support from these tests.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "version": "0.4.0",
+  "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "LICENSE",
+    "LICENSES",
+    "README.md",
+    "docs/app-local-modal.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./theme.css": "./dist/theme.css",
+    "./themes/dsm7.css": "./dist/themes/dsm7.css",
+    "./themes/dsm7-embedded.css": "./dist/themes/dsm7-embedded.css",
+    "./themes/dsm7-embedded-reset.css": "./dist/themes/dsm7-embedded-reset.css",
+    "./themes/dsm7-embedded-theme.css": "./dist/themes/dsm7-embedded-theme.css"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@internationalized/date": "3.12.4",
+    "@lucide/vue": "1.48.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "config": {
+    "bundledRuntime": {
+      "reka-ui": "2.10.5"
+    }
+  },
+  "name": "@synopackageland/ui",
+  "homepage": "https://www.varvis.me/docs/",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}