nativescript-web-adapter 0.1.1 → 0.1.3

package/README.md

@@ -1,190 +1,242 @@
 # NativeScript for Web
 
-Read this in Chinese: [README_ZH.md](README_ZH.md)
+中文: [README_ZH.md](README_ZH.md)
 
-Map common NativeScript UI tags to browser-ready Vue 3 components, enabling the same SFC to run on both Native and Web. Inspired by React Native for Web.
+[![npm](https://img.shields.io/npm/v/nativescript-web-adapter.svg?logo=npm&label=npm)](https://www.npmjs.com/package/nativescript-web-adapter)
+[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-— Ideal for quickly previewing, debugging, or shipping a simplified web version of existing NativeScript Vue projects.
+This project is a “web adapter” for NativeScript‑Vue‑Vite. It can transform native app code into a pure Vue Web project that runs in the browser (generated under `platforms/web/`).
 
-## Features
+---
 
-- Same tag names: use `Page`, `ActionBar`, `GridLayout`, `Label`, `Button`, `ImageCacheIt` directly in SFCs.
-- Prop and event mapping: common props/events are translated to DOM (e.g., `tap` → `click`).
-- Lightweight implementation: focuses on frequently used layouts and controls.
-- Pluggable: registered as a Vue plugin; no invasive app changes.
+## Quick Start
 
-## Installation
+Temporarily add the local bin to `PATH` to make the `ns-web` command available:
 
-Install the adapter from npm:
-
-```
-npm install nativescript-web-adapter
-```
-
-This package expects `vue` as a peer dependency. If not already present:
-
-```
-npm install vue@^3.4.0
+```bash
+export PATH="$PWD/node_modules/.bin:$PATH"
 ```
 
-## Quick Start (Web)
+Compile the web template – install dependencies – start the web project's dev server:
 
-1) Register the plugin
+Web
 
-```ts
-// src/web/main.ts
-import { createApp } from 'vue';
-import { NativeScriptWebPlugin } from 'nativescript-web-adapter';
-import Home from '@/components/Home.vue';
-import '@/app.css';
-
-const app = createApp(Home);
-app.use(NativeScriptWebPlugin);
-app.mount('#app');
-```
-
-2) Vite aliases (map NS deps to the adapter for browser)
-
-```ts
-// vite.web.config.ts
-import { defineConfig } from 'vite';
-import vue from '@vitejs/plugin-vue';
-import path from 'path';
-
-export default defineConfig({
-  plugins: [vue()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, 'src'),
-      '~': path.resolve(__dirname, 'src'),
-      // map SFC imports of nativescript-vue to browser vue
-      'nativescript-vue': 'vue',
-      // map @nativescript/core types/APIs to adapter core (browser-only)
-      '@nativescript/core': 'nativescript-web-adapter/core'
-    }
-  }
-});
+```bash
+ns-web dev
 ```
 
-3) Start the dev server
+iOS
 
 ```bash
-npm run dev:web
-```
-
-## Usage Example
-
-```vue
-<template>
-  <Frame>
-    <Page class="bg-[#251353]">
-      <ActionBar>
-        <Label text="ViteConf 2025" class="font-bold text-lg" />
-      </ActionBar>
-
-      <GridLayout rows="auto,*">
-        <ImageCacheIt
-          src="https://example.com/cover.jpg"
-          stretch="aspectFill"
-          class="align-top"
-          style="width:100dvw"
-        />
-
-        <GridLayout row="1" rows="*,auto,*" class="gradient-purple p-6">
-          <Label
-            class="text-xl align-middle text-center text-[#77c9fa] font-bold"
-            text="Hype Counter: 31485"
-          />
-
-          <Button
-            row="1"
-            class="p-6 text-white font-bold border-4 border-[#77c9fa] rounded-lg text-xl gradient-light-purple"
-            horizontalAlignment="center"
-          >
-            Enter Now
-          </Button>
-        </GridLayout>
-      </GridLayout>
-    </Page>
-  </Frame>
-  </template>
+ns run ios
 ```
 
-## Component Mapping
-
-- `Page` → DOM `main`
-- `ActionBar` → DOM `header`
-- `Frame` → DOM `div`
-- `Label` → DOM `span`
-- `Button` → DOM `button`
-- `StackLayout` → DOM `div` (`display:flex; flex-direction:column`)
-- `FlexboxLayout` → DOM `div` (`display:flex`; supports `flexDirection`, `justifyContent`, `alignItems`)
-- `GridLayout` → DOM `div` (`display:grid`; details below)
-- `ImageCacheIt` → DOM `img` (simple replacement; uses `img` with `stretch` support)
-
-## GridLayout: Design & Behavior
-
-- Container styles
-  - `display: grid`
-  - `grid-template-columns`: defaults to single column `1fr` when `columns` is not provided
-  - `grid-template-rows`: parsed from `rows` (optional)
-  - `grid-auto-flow: row`: auto-stacks vertically by rows
-  - `width: 100%`, `height: 100%`
-
-- Track parsing (`rows`/`columns`)
-  - Comma-separated: e.g., `"auto,*"`, `"*,auto,*"`
-  - `*` → `1fr`, `auto` → `auto`, numbers → pixels (e.g., `60` → `60px`)
-  - Example: `rows="auto,*"` → `grid-template-rows: auto 1fr`
+Android
 
-- Child placement & span
-  - Indexing: NativeScript is 0-based; CSS Grid is 1-based. `row=0` → `grid-row-start:1`, `col=0` → `grid-column-start:1`
-  - Default column: if `col`/`column` is not set, we enforce `grid-column-start:1` to avoid implicit multi-column side-by-side layout
-  - Span: `rowSpan` → `grid-row-end: span n`; `colSpan` → `grid-column-end: span n`
-
-- Alignment
-  - Horizontal: `horizontalAlignment` (`left|center|right|stretch`) → `justify-self`
-  - Vertical: `verticalAlignment` (`top|center|bottom|stretch`) → `align-self`
-
-## Other Props & Events
-
-- Events: `tap` → DOM `click` (the adapter emits `tap` on `onClick`)
-- `Label` alignment: `horizontalAlignment="center"` → `text-align:center`
-- `ImageCacheIt`:
-  - `stretch="aspectFill"` → `object-fit: cover`
-  - `stretch="aspectFit"` → `object-fit: contain`
-  - default styles: `width:100%`, `display:block`, `object-position:center`
-
-## Layout Tips (Aligning Web with iOS)
-
-- Make the outer `main` full viewport height: `main { height: 100vh; }` to match Grid remaining-space behavior.
-- For full-width images: use `style="width:100dvw"` or container `width:100%`; ensure no implicit columns. Optionally set inner `GridLayout` `columns="1*"`.
-- If children appear side-by-side: check if `columns` is declared or `col` is set; by default we fix to column 1.
-
-## Compatibility & Limitations
-
-- The adapter focuses on common UI/layout features; complex native measurements, animations, and platform APIs are out of scope for the browser.
-- Visual differences (fonts, line height, shadows) exist between iOS/Android and browsers; tweak via Tailwind/CSS.
-- Events follow the DOM model; certain native events are not applicable.
-
-## Development & Build
-
-- Build the adapter: `npm run build` (outputs `dist/index.js`, `dist/vue.js`, `dist/core.js` and types)
-- Run tests: `npm run test`
-- Demo project in this repo: `npm run dev:web` starts the browser preview.
-
-## Package Structure (Adapter Subpackage)
-
-- `src/vue/components/*`: implementation of UI components
-- `src/vue/index.ts`: Vue plugin entry (registers all components)
-- `src/core`: minimal types/placeholders for `@nativescript/core` in browser
-- `dist/*`: build outputs and type declarations
-
-## Design Rationale
+```bash
+ns run android
+```
 
-- Keep NativeScript tag parity to reduce migration and dual-edge maintenance costs.
-- Use standard web layout primitives (Flex/Grid) for debuggability and extensibility.
-- Clear mapping rules: 0→1 index conversion, `*`/`auto`/px track parsing, and alignment/span mapping — minimal surprises.
+## Table of Contents
+
+- Background & Goals
+- Tech Stack & Dependencies
+- Native Side (NativeScript)
+- Web Side (Generated Vue Project)
+- Web Adapter (Generator & Package)
+- Run & Build
+- Transformation & Adaptation Rules (Detailed)
+- Styles & Tailwind Configuration
+- Types & TS Configuration
+- HMR (Hot Module Replacement)
+- FAQ & Limitations
+- Improvements & Upgrade Suggestions
+
+---
+
+## Background & Goals
+
+- Provide a native app example using `nativescript-vue` + `@nativescript/vite`, showcasing development and HMR on iOS/Android.
+- Provide a “web adapter” (local package `nativescript-web-adapter`) that scans and transforms the project's `src/` code to generate a Vue application that runs in the browser, enabling quick preview and collaboration on desktop browsers.
+- The generated Web project lives in `platforms/web/` with its own Vite config, dependencies, and entry files, without affecting the native side.
+
+---
+
+## Tech Stack & Dependencies
+
+- Native side (NativeScript):
+  - `nativescript-vue@3.0.1` (uses `patch-package` to inject HMR helpers)
+  - `@nativescript/core@alpha`, `@nativescript/vite@^0.0.1-alpha.7` (NativeScript v9 prerelease)
+  - Example native plugins: `@triniwiz/nativescript-image-cache-it`, `@valor/nativescript-websockets`, `nativescript-inappbrowser`
+- Web side (generated project):
+  - `vue@^3.4`, `vue-router@^4.2`
+  - `vite@^5`, `@vitejs/plugin-vue@^5`
+  - `tailwindcss@^3.4`, `postcss`, `autoprefixer`
+- Adapter package (local):
+  - `nativescript-web-adapter/` uses Vite library mode to build UMD/ESM, with built-in generator scripts and a simple CLI.
+
+---
+
+## Native Side (NativeScript)
+
+- Entry `src/app.ts`:
+  - Starts the native app via `createApp(Home).start()` from `nativescript-vue`.
+  - Registers the native element `ImageCacheIt`.
+  - On Android, uses `Application.on(Application.launchEvent)` to adjust system status/navigation bar styles.
+- Page `src/components/Home.vue`:
+  - Uses NS layouts and components such as `Frame/Page/ActionBar/GridLayout/Label/Button/ImageCacheIt`.
+  - Uses `@tap` to open native links (iOS uses `UIApplication.openURL`, Android uses `Intent`).
+  - Maintains a simple counter in `mounted/unmounted` to demonstrate HMR and state refresh.
+- Global init `src/globals.ts`:
+  - Defines touch animations (iOS: `UIView.animate`, Android: `View.animate`), replaced by a no‑op shim on the Web side.
+- Native Vite config `vite.config.ts`:
+  - `export default defineConfig(({ mode }) => mergeConfig(vueConfig({ mode }), {}))` merges the NS official Vite template to support HMR and build.
+- Tailwind & styles:
+  - `src/app.css` defines theme colors and gradient classes (`gradient-purple/gradient-light-purple`), and sets the `ActionBar` primary color.
+  - `tailwind.config.js` uses `darkMode: ["class", ".ns-dark"]` and disables `preflight` (matching native rendering).
+
+---
+
+## Web Side (Generated Vue Project)
+
+- Output location: `platforms/web/`
+- Example structure:
 
-## Feedback & Improvements
+```
+platforms/web/
+  package.json          # generated (includes vue + vue-router)
+  vite.config.ts        # generated (server.port = 3005, strictPort = true)
+  index.html
+  postcss.config.js
+  tailwind.config.js
+  src/
+    App.vue             # root component (<router-view />)
+    app.ts              # entry (register adapter web components, mount '#app')
+    router/index.ts     # default route (Home)
+    globals.ts          # web shim: initGlobals() no-op
+    components/
+      Home.vue          # copied and transformed from native
+      websfc/           # adapter web components (ActionBar/Page/Frame)
+    composables/
+      websfc/           # adapter composables (useActionBar/usePage/useFrame)
+```
 
-Try it in your projects and share feedback. If you need more components or refined behaviors (absolute positioning, interactions), add implementations under `src/vue/components` following the existing pattern, and submit a PR.
+- Default dev URL: `http://localhost:3005/` (if the port is taken, it fails directly; set `strictPort` to `false` in `vite.config.ts` to enable fallback).
+
+---
+
+## Web Adapter (Generator & Package)
+
+- Location: `nativescript-web-adapter/`
+- Key files:
+  - `tools/create-web-platform.cjs`: generation script (copy, transform, write templates).
+  - `core/components/*.vue`: web SFC containers (`ActionBar/Page/Frame`).
+  - `core/composables/*.ts`: composables (`useActionBar/usePage/useFrame`).
+  - `core/types.ts`: component type aliases and composable type exports.
+  - `index.ts`: adapter installer (`install(app)` registers components and attaches `$ns`).
+  - `vite.config.ts`: library mode build (`external: ['vue']`, outputs UMD/ESM).
+- CLI: `tools/cli.cjs`
+  - Local command: `node nativescript-web-adapter/tools/cli.cjs init`
+  - Includes a `create:web` NPM script (for the root project to call).
+
+---
+
+## Run & Build
+
+- Native side (with HMR):
+  - `npm run dev:ios`: run Vite (port `5173`) and NS iOS debug in parallel.
+  - `npm run dev:android`: run Vite and NS Android debug in parallel.
+  - `npm run ios` / `npm run android`: use `ns debug` for debugging builds.
+- Generate and run the Web project:
+  - `npm run dev:web`: run the adapter generator, then enter `platforms/web`, install deps, and start the Web Vite dev server.
+  - On first run, it creates `platforms/web` along with required templates and configuration.
+
+---
+
+## Transformation & Adaptation Rules (Detailed)
+
+The generator’s `transformContent()` currently performs only necessary code‑level replacements and no longer replaces NS tags in SFC templates with native HTML tags; the UI is handled by custom web components.
+
+- Import replacements and removals:
+  - `from 'nativescript-vue'` → `from 'vue'`
+  - Remove `import ... from '@nativescript/core'` (the web build does not load the native runtime)
+  - Remove `import ... from '@nativescript/web-adapter'` (the generated web project uses local components directly)
+- Platform declarations and native calls cleanup:
+  - Remove common native declarations (e.g., `declare var com;`).
+  - Remove `Application.on(...)` and similar platform event registrations (including those with `__ANDROID__` or `Application.launchEvent`).
+- Template retains NS tags:
+  - Components kept and registered on the Web: `ActionBar/Page/Frame/StackLayout/GridLayout/FlexboxLayout/WrapLayout/ScrollView/Label/Button/Image/HtmlView/ImageCacheIt`.
+  - Special downgrade: `ImageCacheIt` is implemented as a simple `<img>` on the Web (also provided as a web component of the same name for consistent usage).
+- Unified native link opening logic:
+  - Replace the example `enterNow(...)` with the browser implementation: `window.open('https://viteconf.amsterdam', '_blank')`.
+- Other cleanup:
+  - Remove lines involving `android.*`, `UIApplication`, `NSURL`, `NSDictionary`, `intent`, etc.
+  - Remove leftover `else { ... }` native branch blocks.
+  - Comment out `registerElement(...)` (not needed on the Web).
+- Special file handling:
+  - Replace `globals.ts` with a no‑op shim: `export function initGlobals() { /* web shim: no-op */ }`.
+
+> Tip: The current transformation is regex‑driven and covers common patterns. For complex conditional branches, dynamic templates, and advanced native APIs, consider moving to TypeScript/Vue SFC AST‑based transformations to improve accuracy and maintainability.
+
+---
+
+## Styles & Tailwind Configuration
+
+- Native side:
+  - `src/app.css` uses `@tailwind base/components/utilities` and defines theme styles and gradient backgrounds.
+  - `tailwind.config.js`:
+    - `content: ["./src/**/*.{css,vue,ts,tsx}"]`
+    - `darkMode: ["class", ".ns-dark"]`
+    - `corePlugins.preflight: false` (disables browser preset resets)
+- Web side (generated):
+  - `tailwind.config.js` scans `./index.html` and `./src/**/*.{vue,js,ts,jsx,tsx}` and uses standard browser presets.
+  - `postcss.config.js`: enables `tailwindcss` and `autoprefixer`.
+
+---
+
+## Types & TS Configuration
+
+- Root `tsconfig.json`:
+  - `strict: true`, target and module set to `esnext`.
+  - Path aliases: `~/*`, `@/*` → `src/*`.
+  - `vueCompilerOptions.lib = "nativescript-vue"` instructs SFC compilation for the NS environment.
+- Type declarations:
+  - Native side `types/shims.vue.d.ts`: points `*.vue` types to `nativescript-vue`’s `DefineComponent`.
+  - Adapter side `core/env.d.ts`: points `*.vue` types to `vue`’s `DefineComponent`, consistent with browser compilation.
+- Adapter `core/types.ts`: provides type aliases for `ActionBar/Page/Frame` components and exports state types for `useActionBar/usePage/useFrame`.
+
+---
+
+## HMR (Hot Module Replacement)
+
+- Native side:
+  - Uses `@nativescript/vite` with `vite serve -- --env.hmr` to establish an HMR channel, pushing changes to the device.
+  - `patches/nativescript-vue+3.0.1.patch` injects within `app.start`: `globalThis.__NS_VUE_APP__ = app`, helping restore state in deep navigation stacks (e.g., when returning during HMR).
+- Web side:
+  - Independent Vite (`platforms/web/vite.config.ts`) runs on port `3005`, using standard Vue HMR and route refresh.
+
+---
+
+## FAQ & Limitations
+
+- Native APIs & plugins:
+  - Complex native interactions (platform‑specific modules, system services) cannot be automatically converted to the Web. They require manual replacement or browser fallback implementations (e.g., `InAppBrowser` → `window.open` wrapper).
+- Layout & semantic mapping is limited:
+  - Basic web components are provided (`ActionBar/Page/Frame/Grid/Stack/Flex/Wrap/Scroll/Label/Button/Image/HtmlView/ImageCacheIt`). More detailed property‑to‑style mappings will be added later (e.g., `flexDirection/row`, grid rows/columns).
+- Regex‑driven transformation:
+  - Edge cases may exist for complex code and templates. Gradually moving to AST‑level transformation is recommended.
+- Generator template duplicate writes:
+  - The generator currently writes `platforms/web/package.json` twice (with different dependency versions). This can be streamlined into a single write to reduce maintenance cost.
+
+---
+
+## Improvements & Upgrade Suggestions
+
+1. Transformation engine upgrade:
+   - Replace regex with TypeScript and Vue SFC AST to precisely handle imports, calls, templates, and directive mappings.
+2. Global initialization & animations:
+   - Provide optional web animation implementations (CSS transitions/GSAP) for `globals.ts` to keep interaction behavior consistent.
+3. Tests & validation:
+   - Add unit tests and e2e tests for transformation rules and template generation to ensure stability across different project structures.
+
+---

package/core/components/AbsoluteLayout.vue

@@ -0,0 +1,11 @@
+<template>
+  <div class="ns-absolute"><slot /></div>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: 'AbsoluteLayout' });
+</script>
+
+<style scoped>
+.ns-absolute { position: relative; width: 100%; height: 100%; }
+</style>

package/core/components/ActionBar.vue

@@ -0,0 +1,11 @@
+<template>
+  <header class="ns-actionbar"><slot /></header>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: 'ActionBar' });
+</script>
+
+<style scoped>
+.ns-actionbar { background: #1f1140; color: white; padding: 12px; }
+</style>

package/core/components/ActionItem.vue

@@ -0,0 +1,11 @@
+<template>
+  <button class="ns-actionitem"><slot /></button>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: 'ActionItem' });
+</script>
+
+<style scoped>
+.ns-actionitem { background: transparent; border: none; color: inherit; cursor: pointer; padding: 8px; }
+</style>

package/core/components/ActivityIndicator.vue

@@ -0,0 +1,15 @@
+<template>
+  <div class="ns-activity-indicator" :class="{ busy }" />
+</template>
+
+<script setup lang="ts">
+const props = defineProps<{ busy?: boolean }>();
+const busy = props.busy ?? true;
+defineOptions({ name: 'ActivityIndicator' });
+</script>
+
+<style scoped>
+.ns-activity-indicator { width: 20px; height: 20px; border-radius: 50%; border: 2px solid rgba(255,255,255,0.3); border-top-color: currentColor; opacity: 0.8; }
+.ns-activity-indicator.busy { animation: ns-spin 0.8s linear infinite; }
+@keyframes ns-spin { to { transform: rotate(360deg) } }
+</style>

package/core/components/Button.vue

@@ -0,0 +1,41 @@
+<template>
+  <button class="ns-button" :style="btnStyle" @click="$emit('tap', $event)"><slot /></button>
+  
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+defineOptions({ name: 'Button' });
+const emit = defineEmits<{ (e: 'tap', evt: MouseEvent): void }>();
+const props = defineProps<{ horizontalAlignment?: string }>();
+
+const btnStyle = computed<Record<string, string>>(() => {
+  const style: Record<string, string> = {};
+  const h = props.horizontalAlignment?.toLowerCase();
+  if (h === 'center') {
+    style.display = 'block';
+    style.width = 'fit-content';
+    style.marginLeft = 'auto';
+    style.marginRight = 'auto';
+    style.alignSelf = 'center';
+    style.justifySelf = 'center';
+  } else if (h === 'right') {
+    style.display = 'block';
+    style.width = 'fit-content';
+    style.marginLeft = 'auto';
+    style.alignSelf = 'flex-end';
+    style.justifySelf = 'end';
+  } else if (h === 'left') {
+    style.display = 'block';
+    style.width = 'fit-content';
+    style.marginRight = 'auto';
+    style.alignSelf = 'flex-start';
+    style.justifySelf = 'start';
+  }
+  return style;
+});
+</script>
+
+<style scoped>
+.ns-button { cursor: pointer; }
+</style>

package/core/components/DatePicker.vue

@@ -0,0 +1,27 @@
+<template>
+  <input class="ns-datepicker" type="date" :value="valueStr" @input="onInput" />
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+defineOptions({ name: 'DatePicker' });
+const props = defineProps<{ date?: string | Date }>();
+const emit = defineEmits<{ (e: 'update:date', v: string | Date): void; (e: 'change', v: string | Date): void }>();
+
+function pad(n: number) { return n < 10 ? `0${n}` : String(n); }
+const valueStr = computed(() => {
+  if (!props.date) return '';
+  const d = typeof props.date === 'string' ? new Date(props.date) : props.date;
+  if (isNaN(d.getTime())) return '';
+  return `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())}`;
+});
+function onInput(e: Event) {
+  const v = (e.target as HTMLInputElement).value;
+  emit('update:date', v);
+  emit('change', v);
+}
+</script>
+
+<style scoped>
+.ns-datepicker { padding: 6px 8px; }
+</style>

package/core/components/DockLayout.vue

@@ -0,0 +1,23 @@
+<template>
+  <div class="ns-dock">
+    <div class="ns-dock-top"><slot name="top" /></div>
+    <div class="ns-dock-middle">
+      <div class="ns-dock-left"><slot name="left" /></div>
+      <div class="ns-dock-center"><slot /></div>
+      <div class="ns-dock-right"><slot name="right" /></div>
+    </div>
+    <div class="ns-dock-bottom"><slot name="bottom" /></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: 'DockLayout' });
+</script>
+
+<style scoped>
+.ns-dock { display: flex; flex-direction: column; width: 100%; height: 100%; }
+.ns-dock-top, .ns-dock-bottom { flex: 0 0 auto; }
+.ns-dock-middle { display: flex; flex: 1 1 auto; min-height: 0; }
+.ns-dock-left, .ns-dock-right { flex: 0 0 auto; }
+.ns-dock-center { flex: 1 1 auto; min-width: 0; }
+</style>

package/core/components/FlexboxLayout.vue

@@ -0,0 +1,11 @@
+<template>
+  <div class="ns-flex"><slot /></div>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: 'FlexboxLayout' });
+</script>
+
+<style scoped>
+.ns-flex { display: flex; }
+</style>

package/core/components/Frame.vue

@@ -0,0 +1,11 @@
+<template>
+  <div class="ns-frame"><slot /></div>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: 'Frame' });
+</script>
+
+<style scoped>
+/* .ns-frame {  } */
+</style>

package/core/components/GridLayout.vue

@@ -0,0 +1,85 @@
+<template>
+  <div class="ns-grid" :style="gridStyle">
+    <template v-for="(child, idx) in renderedChildren" :key="idx">
+      <component :is="child" />
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, useSlots, cloneVNode } from 'vue';
+
+defineOptions({ name: 'GridLayout' });
+const props = defineProps<{ rows?: string; columns?: string }>();
+
+function parseSegments(input?: string): string | undefined {
+  if (!input) return undefined;
+  const segToCss = (s: string) => {
+    const t = s.trim();
+    if (!t) return 'auto';
+    if (t === '*') return '1fr';
+    const star = t.match(/^(\d+)\*$/);
+    if (star) return `${star[1]}fr`;
+    if (t.toLowerCase() === 'auto') return 'auto';
+    if (/^\d+$/.test(t)) return `${t}px`;
+    return t; // passthrough for e.g. '1fr' or '50px'
+  };
+  return input.split(',').map(segToCss).join(' ');
+}
+const gridStyle = computed<Record<string, string>>(() => {
+  const style: Record<string, string> = { display: 'grid' };
+  const rows = parseSegments(props.rows);
+  const cols = parseSegments(props.columns);
+  if (rows) style.gridTemplateRows = rows;
+  if (cols) style.gridTemplateColumns = cols;
+  return style;
+});
+
+// 根据子元素 row/col/rowSpan/colSpan 设置 CSS Grid 定位
+const slots = useSlots();
+const renderedChildren = computed(() => {
+  const nodes = slots.default ? slots.default() : [];
+  return nodes.map((node: any) => {
+    const props = (node && node.props) ? (node.props as Record<string, any>) : {};
+    const parseNum = (v: any) => v === undefined || v === null ? undefined : Number(v);
+    const row = parseNum(props.row);
+    const col = parseNum(props.col);
+    const rowSpan = parseNum(props.rowSpan);
+    const colSpan = parseNum(props.colSpan);
+
+    const style: Record<string, any> = {};
+    if (row !== undefined && !Number.isNaN(row)) {
+      const start = (row ?? 0) + 1; // CSS Grid 1-indexed
+      const span = rowSpan && rowSpan > 0 ? rowSpan : 1;
+      style.gridRow = `${start} / span ${span}`;
+    }
+    if (col !== undefined && !Number.isNaN(col)) {
+      const start = (col ?? 0) + 1; // CSS Grid 1-indexed
+      const span = colSpan && colSpan > 0 ? colSpan : 1;
+      style.gridColumn = `${start} / span ${span}`;
+    }
+
+    const existingStyle = props.style as any;
+    let mergedStyle: any;
+    if (Array.isArray(existingStyle)) mergedStyle = [...existingStyle, style];
+    else if (existingStyle && typeof existingStyle === 'object') mergedStyle = { ...existingStyle, ...style };
+    else if (typeof existingStyle === 'string') mergedStyle = [existingStyle, style];
+    else mergedStyle = style;
+
+    return cloneVNode(node, { style: mergedStyle });
+  });
+});
+</script>
+
+<style scoped>
+.ns-grid { 
+  padding: 0px;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  min-width: 0;
+  min-height: 0;
+  /* flex: 1 1 auto;
+  gap: 50px; */
+ }
+</style>