@synopackageland/ui 0.20.5 → 0.20.7

package/docs/layout-rules.md

@@ -28,7 +28,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 
 - Labels sit above their controls (`Form direction="vertical"`), except in short DSM-style dialogs and in side sheets (drawers).
 - In a dialog or a side `Sheet`, keep the default `direction="auto"`: as in DSM, the labels sit in a left column whenever the form is at least 400px wide (a 420–480px sheet) and stack above their controls only below that (a phone). Size the column with `Form label-width` (about 120px for short labels); a long label wraps inside it and stays level with its control's first line, whether that is a field, a select, a switch, a toggle group or a segment control.
-- Size a field by its content: number fields are 128px; text fields use `fieldWidth`. Put two short fields side by side rather than stretching one across the page.
+- Size a field by its content: number fields are 128px; text fields use `fieldWidth`; in a narrow row that stacks its label (a phone), `md` and `lg` fill the column. Put two short fields side by side rather than stretching one across the page.
 - A checkbox's text sits on the same line as its box. Do not apply `display: grid` to `label` in App CSS; `Checkbox` renders its own label.
 - For 2–4 mutually exclusive settings, use `RadioGroup` (vertical by default, `orientation="horizontal"` when labels fit). In a wizard step, `variant="card"` draws the options as choice cards with an optional `icon` each. A checkbox enables an independent option; a switch turns a feature on or off immediately. Keep the circular radio with a dot, square checkbox with a tick, and pill switch with a moving thumb.
 - Reserve `SegmentControl` for toolbar view switching: its selected item is a primary-filled capsule. `variant="sheet"` and `SectionTabs` are navigation tabs. Do not use either as a form value selector.

package/docs/mobile-native.md

@@ -469,8 +469,8 @@ unchanged.
 
 **DataGrid and DataTable.** `mobile-view="auto"` (the default) shows a list
 instead of the table. Each row is at least `--ui-list-row-height` (48px on a
-phone): the title column on the first line, up to two columns joined with `·`
-on the second, and trailing columns at the end. Columns place themselves with
+phone): the title column on the first line, up to two columns on the second
+with a small gap between them, and trailing columns at the end. Columns place themselves with
 `list`:
 
 | `list` | Place |

package/docs/ux-grid.md

@@ -1,7 +1,7 @@
 # Grid range, fill and clipboard
 
-`@synopackageland/ui/grid` draws a canvas grid (a Vue port of Teable's MIT
-grid core) and owns geometry, scroll, selection, focus and pointer feedback.
+`@synopackageland/ui/grid` draws a canvas grid on `src/grid-core` and owns
+geometry, scroll, selection, focus and pointer feedback.
 It never writes data. Every change a user asks for (an edit, a clear, a fill,
 a paste, a reorder, a width) comes out as an event; the caller applies it to
 its row model as one undoable change and saves in the background.
@@ -124,8 +124,7 @@ from text the caller read itself.
 
 ## Touch and phone
 
-Interaction-spec §14, adapted to Teable's touch grid. Two switches, kept
-apart:
+Interaction-spec §14, adapted for touch. Two switches, kept apart:
 
 - **Touch UI**: `(pointer: coarse)`. No fill handle and no column resize
   handle are drawn or hit (a 5 px edge is no finger target).
@@ -162,7 +161,7 @@ Android's own long-press `contextmenu`, are ignored for 800 ms after a finger.
 - The gutter is 50 px with row numbers only: `rowControls` are not drawn and
   not hit; a row-header tap opens the record.
 - Wider screens, touch or not, cap frozen columns so the scrolling part keeps
-  at least 240 px (Teable's `getMaxFreezeColumnCount`).
+  at least 240 px.
 - Row and header height follow the density tokens: the DSM 7 theme gives
   36 px on a coarse pointer unless the app sets `data-ui-density`.
 - The grid draws no append row; the host offers its own add button.
@@ -209,9 +208,8 @@ Before a release that changes `@synopackageland/ui/grid`:
    the record, a tablet second tap does not edit, a finger edit keeps focus,
    or a long press does not open exactly one context menu.
 5. `node scripts/check-package-content.mjs`: `dist/grid.js` imports only
-   `vue` and `./index.js` and keeps the Teable notice.
-6. Notices: `LICENSES/ux-grid-teable.md` and `LICENSES/ux-grid-baserow.md`
-   ship in the package.
+   `vue` and `./index.js` and keeps the MIT notice.
+6. Notices: `LICENSES/source-notices.md` ships in the package.
 7. Manual, not covered headless: IME first character in Safari, native
    macOS Cmd+C/X/V into Excel, Numbers and Google Sheets, and on a real
    iPhone that a second tap brings up the keyboard and Return puts it away.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,6 @@
     "docs/release-checks.md",
     "docs/size-and-split.md",
     "docs/theme-hooks.md",
-    "docs/ux-foundation.md",
     "docs/ux-grid.md",
     "docs/wizard.md"
   ],
@@ -61,58 +60,6 @@
     "./themes/dsm7-embedded-reset.css": "./dist/themes/dsm7-embedded-reset.css",
     "./themes/dsm7-embedded-theme.css": "./dist/themes/dsm7-embedded-theme.css"
   },
-  "scripts": {
-    "check:docs": "node --test scripts/check-doc-versions.test.mjs && node scripts/check-doc-versions.mjs",
-    "dev": "vite build --watch",
-    "build": "vite build && vite build --mode json && vite build --mode rich-text && vite build --mode grid && vite build --mode cli && vite build --mode preview && vite build --mode embedded && node scripts/postbuild.mjs",
-    "lint": "eslint .",
-    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:changed": "echo \"test:changed skips the tests the changes since ${SYNOPKGLAND_GATE_BASE:-origin/master} do not reach (vitest --changed); pnpm check runs them all\" && vitest run --changed ${SYNOPKGLAND_GATE_BASE:-origin/master}",
-    "story": "histoire dev",
-    "story:build": "histoire build",
-    "check:host": "node scripts/dsm-host-shots.mjs",
-    "check:switch": "node scripts/check-switch.mjs",
-    "check:tabs": "node scripts/check-tabs.mjs",
-    "check:mobile": "node scripts/check-mobile-overflow.mjs",
-    "check:narrow": "node scripts/check-narrow-controls.mjs",
-    "check:drawer-form": "node scripts/check-drawer-form.mjs",
-    "check:responsive": "node scripts/check-responsive.mjs",
-    "check:adaptive": "node scripts/check-adaptive.mjs",
-    "check:sidebar-focus": "node scripts/check-sidebar-focus.mjs",
-    "check:json-render": "node scripts/check-json-render.mjs",
-    "check:motion": "node scripts/check-motion.mjs",
-    "check:topology": "node scripts/check-topology.mjs",
-    "check:wizard": "node scripts/check-wizard.mjs",
-    "check:edges": "node scripts/check-edges.mjs",
-    "check:data-grid": "node scripts/check-data-grid.mjs",
-    "check:truncation": "node scripts/check-truncation.mjs",
-    "check:link": "node scripts/check-link.mjs",
-    "check:text-select": "node scripts/check-text-select.mjs",
-    "check:date-picker": "node scripts/check-date-picker.mjs",
-    "check:full-page": "node scripts/check-full-page.mjs",
-    "check:detail-surface": "node scripts/check-detail-surface.mjs",
-    "check:internal": "node --test scripts/check-internal-content.test.mjs scripts/check-npm-metadata.test.mjs && node scripts/check-internal-content.mjs --repo .",
-    "check:npm-metadata": "node scripts/check-npm-metadata.mjs",
-    "check:package": "node scripts/check-package-content.mjs",
-    "check:ux-foundation-consumer": "node scripts/check-ux-foundation-consumer.mjs",
-    "notices:update": "node scripts/third-party-notices.mjs --write",
-    "notices:check": "node scripts/third-party-notices.mjs --check",
-    "check": "bash scripts/docker-check.sh \"npm run gates\"",
-    "check:fast": "bash scripts/docker-check.sh \"npm run gates\"",
-    "check:local-browser": "node scripts/app-local-browser.mjs",
-    "check:infotip": "node scripts/check-infotip.mjs",
-    "release:stage": "node scripts/stage-release.mjs",
-    "check:polish": "bash scripts/docker-check.sh --build --out .polish-shots 'node scripts/check-polish.mjs'",
-    "check:acceptance": "node scripts/check-acceptance.mjs",
-    "check:palette": "node scripts/check-palette.mjs",
-    "gates": "node scripts/gates.mjs",
-    "gates:full": "node scripts/gates.mjs --full",
-    "check:layout": "node scripts/check-layout.mjs",
-    "release:smoke": "node scripts/release-smoke.mjs",
-    "check:browser-install": "playwright install chromium"
-  },
   "peerDependencies": {
     "vue": "^3.5.0"
   },
@@ -132,44 +79,9 @@
     "@tiptap/vue-3": "3.32.1",
     "zod": "^4.6.5"
   },
-  "devDependencies": {
-    "@eslint/js": "10.0.1",
-    "@histoire/plugin-vue": "1.0.0-beta.1",
-    "@tailwindcss/vite": "4.3.3",
-    "@tanstack/vue-virtual": "3.13.39",
-    "@vitejs/plugin-vue": "6.0.9",
-    "@vue/test-utils": "2.5.1",
-    "@vueuse/core": "14.4.0",
-    "eslint": "10.11.0",
-    "eslint-plugin-vue": "10.11.1",
-    "flexsearch": "0.8.212",
-    "globals": "17.12.0",
-    "histoire": "1.0.0-beta.1",
-    "jsdom": "30.1.1",
-    "playwright": "1.58.2",
-    "reka-ui": "2.11.0",
-    "tailwindcss": "4.3.3",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.71.0",
-    "vite": "7.3.6",
-    "vite-plugin-dts": "5.1.1",
-    "vitest": "5.0.2",
-    "vscode-oniguruma": "2.0.1",
-    "vscode-textmate": "9.3.2",
-    "vue": "3.5.43",
-    "vue-eslint-parser": "10.4.1",
-    "vue-tsc": "3.3.11"
-  },
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.33.2",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "vue-demi"
-    ]
-  },
   "config": {
     "bundledRuntime": {
       "@tanstack/vue-virtual": "3.13.39",

package/LICENSES/ux-foundation.md

@@ -1,83 +0,0 @@
-# @synopackageland/ui UX foundation: third-party notices
-
-`dist/index.js` contains small ports of MIT-licensed code from Teable and
-Baserow in the interaction core, drag kit, panels and virtual cards. Each
-ported source file keeps the notice below in its header; the built file drops
-those comments and starts with a one-line notice pointing here instead. The
-canvas grid in `dist/grid.js` has its own notices in
-[ux-grid-teable.md](ux-grid-teable.md) and [ux-grid-baserow.md](ux-grid-baserow.md).
-
-Nothing is taken from Teable `apps/*` (AGPL-3.0), Baserow `premium/` or
-`enterprise/` (proprietary) or NocoDB (Sustainable Use License); where those
-projects informed a behaviour, only the technique was used. No Teable or
-Baserow name, logo or icon asset is shipped.
-
-## Ported files
-
-| Source file in this package | Ported from | Upstream commit |
-| --- | --- | --- |
-| `src/interaction/ime.ts` (`isPrintableKey`) | Teable `packages/sdk/src/components/grid/utils/hotkey.ts` | `f8be01fad` |
-| `src/interaction/gesture.ts` (5px threshold, half-item drop rule) | Teable `packages/sdk/src/components/grid/hooks/useDrag.ts:8-119` | `f8be01fad` |
-| `src/components/primitives/popover/overlay.ts` (`skipAutoFocusOnTouch`) | Teable `packages/ui-lib/src/shadcn/ui/popover.tsx:30-45` | `f8be01fad` |
-| `src/components/composite/record-panel/recordPanelWidth.ts` (width rule) | Teable `packages/sdk/src/components/expand-record/Panel.tsx:20-26, 83-88` | `f8be01fad` |
-| `src/components/composite/record-panel/RecordPanel.vue` (sash, clip layer, drag-to-width) | Teable `packages/sdk/src/components/expand-record/Panel.tsx:100-171`, `packages/ui-lib/src/base/resize-handle/ResizeHandleBar.tsx:1-35` | `f8be01fad` |
-| `src/interaction/outside.ts` (outside-press snapshot and ignore list) | Baserow `web-frontend/modules/core/utils/dom.js` `onClickOutside` | `98f727dc2` |
-| `src/dnd/dragKit.ts` (buffered-rows drag and drop, 100ms swap lock) | Baserow `web-frontend/modules/database/mixins/bufferedRowsDragAndDrop.js:64-235`, `store/view/bufferedRows.js` | `98f727dc2` |
-| `src/dnd/autoScroll.ts` (edge zone and speed ramp) | Baserow `web-frontend/modules/core/directives/autoScroll.js:30-99` | `98f727dc2` |
-| `src/virtual/cardHeight.ts` (`cardHeight`) | Baserow `web-frontend/modules/database/utils/card.js:1-24` | `aa2402b7c716c3eadc5a382af3e880756e026d9c` |
-
-## Teable licence
-
-Teable `packages/*` is MIT licensed.
-
-```text
-MIT License
-
-Copyright (c) 2023-2025 Teable, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
-## Baserow licence
-
-Baserow Open Source Edition (outside `premium/` and `enterprise/`) is MIT
-(Expat) licensed.
-
-```text
-MIT License
-
-Copyright (c) 2019-present Baserow B.V.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this
-software and associated documentation files (the "Software"), to deal in the Software
-without restriction, including without limitation the rights to use, copy, modify,
-merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to the following
-conditions:
-
-The above copyright notice and this permission notice shall be included in all copies
-or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
-PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
-CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
-OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-```

package/LICENSES/ux-grid-baserow.md

@@ -1,35 +0,0 @@
-# @synopackageland/ui/grid: Baserow notice
-
-`dist/grid.js` (source `src/grid/clipboard/write.ts`, `writeClipboardAsync`)
-contains a TypeScript port of `copySelectionToClipboard` and
-`writeToClipboard` from Baserow's
-`web-frontend/modules/database/mixins/copyPasteHelper.js:147-218` (commit
-`98f727dc2ed8140fe44e3e797eedb05339562659`). The HTML-table rule in
-`src/grid/clipboard/tsv.ts` (`toHtmlTable`: no table for a single cell) follows
-`prepareHTMLData` in the same file. Baserow licenses all client-side
-JavaScript, including that file, under the MIT (Expat) licence below. Nothing
-from Baserow's `premium/` or `enterprise/` directories is included, and no
-Baserow name, logo or other asset is shipped.
-
-## Baserow licence
-
-```text
-Copyright (c) 2019-present Baserow B.V.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this
-software and associated documentation files (the "Software"), to deal in the Software
-without restriction, including without limitation the rights to use, copy, modify,
-merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to the following
-conditions:
-
-The above copyright notice and this permission notice shall be included in all copies
-or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
-PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
-CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
-OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-```

package/LICENSES/ux-grid-teable.md

@@ -1,48 +0,0 @@
-# @synopackageland/ui/grid: third-party notice
-
-`dist/grid.js` (source `src/grid/` and `src/grid-core/`) contains a TypeScript
-port, without React, of the canvas grid in Teable's SDK package
-(`packages/sdk/src/components/grid/`, commit
-`f8be01fadb86790d3d3a878bedd10cf949f9a8f8`, 2026-11-03). That package is MIT
-licensed (`packages/sdk/LICENSE` and `"license": "MIT"` in
-`packages/sdk/package.json` at that commit). Nothing from Teable's `apps/*`
-(AGPL-3.0) is included, and no Teable name, logo or icon asset is shipped.
-
-The Vue host in `src/grid/host/` is new code that follows the coordinate set-up
-in `Grid.tsx` and the pointer flow of `InteractionLayer.tsx`; it calls the
-ported modules and copies no React code. Default theme colours that fill
-missing tokens are Tailwind CSS palette values (MIT, Copyright (c) Tailwind
-Labs, Inc.), as Teable uses them.
-
-The fill-handle gesture in `src/grid/host/controller.ts` and `src/grid/range/`
-follows the fill flow of `InteractionLayer.tsx` (preview over the target rows,
-selection grows on release). The fill value rules, the clipboard TSV
-parser/writer and the paste proposal are new code; Teable's fill and
-copy/paste rules live in AGPL `apps/*` code and were not copied. The async
-clipboard write is ported from Baserow (MIT); see `ux-grid-baserow.md`.
-
-## Teable licence
-
-```text
-MIT License
-
-Copyright (c) 2023-2025 Teable, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```

package/docs/ux-foundation.md

@@ -1,133 +0,0 @@
-# UX foundation: public contract
-
-The building blocks for app views that settle once and do not move again:
-interaction core, drag kit, side regions and panels, virtual cards, feedback
-and motion. Everything here is imported from a package entry; an App never
-imports a source path.
-
-| Entry | What it holds | Load |
-| --- | --- | --- |
-| `@synopackageland/ui` | every name on this page except the grid | normally |
-| `@synopackageland/ui/grid` | `GridHost`, cell renderers, cell theme, save-status store | lazily, when a grid view first opens |
-| `@synopackageland/ui/theme.css` | tokens, chrome and motion | once, at startup |
-
-```ts
-import {
-  AsidePanel, RecordPanel, AdaptivePanel, StatusSlot, VirtualCardGrid, CardCover, CardField,
-  cardHeight, createDragKit, useDragKit, registerOutsideLayer, createEditSession, motionMs,
-} from '@synopackageland/ui'
-
-const GridHost = defineAsyncComponent(() => import('@synopackageland/ui/grid').then(module => module.GridHost))
-```
-
-A consumer fixture that type-checks and imports every name below from the
-packed tarball is in `tests/ux-foundation-consumer/`
-(`node scripts/check-ux-foundation-consumer.mjs`, after `pnpm build`).
-
-## Defaults and opt-in
-
-Nothing here needs a flag. The compact chrome is the only density.
-
-| What | Default | Opt in or change |
-| --- | --- | --- |
-| Web chrome rows (page header, toolbar, sidebar head and footer) | 48px; window and phone keep 44px | none |
-| Chrome controls / header actions / web nav rows / icons | 28px / 32px / 32px / 16px; icon buttons 4px apart | `--ui-nav-row-height`, `--ui-icon-size` ([theme hooks](theme-hooks.md#layout-and-theme-tokens)) |
-| Full-page (`web`) presentation | off; DSM windows stay `window` at any width | `AppLayout wide-layout="web"`: from a 960px container, sidebar starts as the 48px rail below 1200px |
-| Font | system font stack in the `web` presentation | `--ui-font-sans` |
-| Right side region | none | put an `AsidePanel` in `AppLayout`'s `aside` slot; `v-model:aside`, `v-model:aside-width` |
-| Motion | on, with the tokens in [theme hooks](theme-hooks.md#motion) | `data-ui-motion="off"` on any ancestor; reduced motion reads every duration as 0ms |
-| Popup motion inside a grid editor | 150ms in, 100ms out | `provideOverlayMotion('none')` or `motion="none"` |
-| Canvas grid | not loaded | import `@synopackageland/ui/grid` |
-
-## Copy and accessibility
-
-Built-in labels come from the library's nine locales (en, zh-TW, zh-CN, ja,
-ko, de, fr, es, it) and follow `AppRoot locale` (else its `lang`). Names that only the App
-knows are props, already translated: `AsidePanel title`, `RecordPanel label`,
-`AdaptivePanel title`, `VirtualCardGrid label`, `CardField label`,
-`CardCover alt`, `StatusSlot message`. Every built-in label can be replaced
-(`openLabel`, `collapseLabel`, `expandLabel`, `restoreLabel`, `closeLabel`,
-`resizeLabel`, `retryLabel`). No label ends with a period.
-
-## Side regions and panels
-
-| Component | Use | Main props and events |
-| --- | --- | --- |
-| `AppLayout` `aside` slot | the right side region beside the page | `v-model:aside` (`open` / `collapsed` / `expanded`), `v-model:aside-width` (380, 320–560). The slot gets `{ state, overlay, width, presentation }`. An open aside that would leave the page under 480px floats over it; a phone has no region width |
-| `AsidePanel` | the region's content: 48px rail, docked panel, floating panel, phone sheet | `title`, `icon`, `unread`, `fab`, `expandable`, `initialFocus`, `shortcut`; slots `tabs`, `actions`, default. Never unmounted, so scroll and drafts survive a collapse |
-| `useAsidePreference(key, scope)` | the stored state and width, read before first paint | `readAsidePreference`, `writeAsidePreference`, `clampAsideWidth` |
-| `RecordPanel` | a non-modal record panel docked over the view; the view never changes width | `v-model:open`, `v-model:width`, `storageKey`, `secondaryOpen`, `container`, `compactBelow`, `returnFocus`, `initialFocus`, `flush`; `close(reason)`, `resizeEnd`; slots `header`, default, `secondary` |
-| `AdaptivePanel` | a popover in a wide host, a bottom sheet at 640px and narrower; the content is mounted once | `v-model:open`, `title`, `side`, `align`, `width`, `sheetSide`, `sheetSize`, `compactBelow`, `container`, `motion` |
-
-`APP_ASIDE_KEY` and `APP_SIDE_MOTION_KEY` are injection keys for content that
-must react to the region; `WEB_ASIDE_DEFAULT`, `WEB_ASIDE_MIN`,
-`WEB_ASIDE_MAX`, `WEB_RAIL_WIDTH`, `WEB_RAIL_BELOW`, `WEB_LAYOUT_MIN` and
-`MOBILE_LAYOUT_MAX` are the sizes.
-
-## Feedback
-
-| Name | Contract |
-| --- | --- |
-| `SectionSkeleton` `variant="grid" \| "cards" \| "fields"` | the final geometry from the first frame; shapes show after 300ms |
-| `useToast()` | success 3s, info and warning 5s (at least 5s with an action), danger stays; `pending()` shows after 300ms and becomes its result through `update(id)` |
-| `StatusSlot` | a fixed box for `pending` / `saved` / `error` (with Retry); empty while idle, so nothing moves |
-| `useShowAfter(active, { delay })` | true only once `active` has held for the delay (300ms, `PENDING_DELAY_MS`) |
-| `TOAST_DURATION_MS` | the toast durations by tone |
-
-## Virtual cards
-
-`VirtualCardGrid` renders only the rows on screen. Every card has the height
-`cardHeight({ fields, cover, title })` returns, so nothing is measured, and
-the column count (`galleryColumns(width)`, breakpoints `GALLERY_BREAKPOINTS`)
-is known before the first card renders. The grid emits `range(start, end)` for
-the window to load; an unloaded card is a placeholder of the same size. Put
-`CardCover` in the `cover` slot and `CardField` rows in the body, with the same
-value heights you passed to `cardHeight` (`CARD_VALUE_HEIGHT`, `CARD_METRICS`).
-
-While a side region changes width, the column count holds and settles once at
-the end. `AppLayout` drives this for its sidebar and aside. Anything else that
-moves the width of the main area on purpose calls `useLayoutMotion().track(el)`
-right after it changes the width, or `begin()` and the returned end; a layout
-that only moves its own region gives its children `provideLayoutMotion()`.
-
-## Interaction core
-
-| Name | Contract |
-| --- | --- |
-| `registerOutsideLayer` / `useOutsideLayer` | one window-capture listener; layers are walked from the top, everything above the pressed layer gets `onOutside` once; `'veto'` blocks the press and its click; Escape goes to the topmost layer only |
-| `IGNORE_OUTSIDE_ATTR` (`data-ui-ignore-outside`) | put it on every portal root that belongs to an interactive surface |
-| `createCompositionGuard`, `isComposingKey`, `isPrintableKey` | Enter, Escape and Tab belong to an IME while it composes and for 50ms after (`COMPOSITION_END_GRACE_MS`) |
-| `focusSync`, `createFocusOwner`, `isInForeignDialog` | focus synchronously in the input handler, never out of a dialog the surface does not own |
-| `trackPointerGesture` / `usePointerGesture`, `dropIndexAt` | 5px threshold (`DRAG_THRESHOLD_PX`), pointer capture, release on cancel, blur or dispose |
-| `createEditSession` / `useEditSession`, `editSessionOutside` | `start` / `setDraft` / `setComposing` / `commit` / `cancel`; a validation veto keeps the editor; a commit waits for the composition to end |
-
-## Drag kit
-
-`createDragKit` (Vue: `useDragKit`) runs one drag across registered lanes:
-5px mouse threshold, 250ms touch hold (`TOUCH_HOLD_MS`), Space and arrow keys,
-edge auto-scroll, Escape rollback. Register a lane with
-`kit.lane({ id, element, count, layout })`: give a virtual lane a fixed
-`dragListGeometry` or `dragGridGeometry`; a rendered lane can use
-`dragMeasuredGeometry`. Spread `kit.item(lane, index, key)` on each item.
-`onDrop({ key, from, to })` runs in the release frame: change the local data
-there and return the server write's promise; a rejection calls `onRestore` and
-the item slides home. The geometry types are exported as `DragRect`,
-`DragAxis`, `DragArrangement`, `DragLaneGeometry` and `DragLaneLayout`.
-`createAutoScroll` and `edgeSpeed` give the same edge scrolling to other
-surfaces.
-
-## Motion helpers
-
-`motionMs(token, el?)` reads a duration token (`MotionToken`) as it resolves
-on `el`, 0 when motion is off for it (`motionOff`, `MOTION_OFF_SELECTOR`).
-`transitionMs(el)` is the longest transition on an element.
-`useSwapMotion(target, source)` plays the switched-content rise-in when
-`source` changes; `useInsertedKeys(keys, options)` returns the keys of rows
-that were just added, so only those animate in.
-
-## Third-party code
-
-Parts of this foundation are ports of MIT code from Teable and Baserow. The
-notices are kept in each ported file and collected in
-`LICENSES/ux-foundation.md`; the grid entry's notices are
-`LICENSES/ux-grid-teable.md` and `LICENSES/ux-grid-baserow.md`; its contract is [ux-grid](ux-grid.md).