{"_id":"@bagaking/dma-frame","_rev":"2-182f62a03e837ff0d008e277bb5521cf","name":"@bagaking/dma-frame","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@bagaking/dma-frame","version":"0.1.0","keywords":["feishu","lark","addon","frame","height-control"],"author":{"name":"bagaking","email":"kinghand@foxmail.com"},"license":"MIT","_id":"@bagaking/dma-frame@0.1.0","maintainers":[{"name":"kinghand","email":"kinghand@foxmail.com"}],"homepage":"https://github.com/bagaking/DMAppFrame#readme","bugs":{"url":"https://github.com/bagaking/DMAppFrame/issues"},"dist":{"shasum":"60207a2c50e1a526b4914e0f5e64a8cfed1c4af3","tarball":"https://registry.npmjs.org/@bagaking/dma-frame/-/dma-frame-0.1.0.tgz","fileCount":14,"integrity":"sha512-GSKiof/RKDy690oPiSI8AdjlNeJyM5Qw73BaS+VO9M2Bw+0vpMcfyRNi94hSObbetPQX8HTCo2Gq0o5TKO7fdQ==","signatures":[{"sig":"MEUCIQC05d2LwRgrbZaesqUidgjMslbnSbLLAFByitCdh01OGwIgH+Qb3JgqvT7WOyYs0z8BkS8443E2m+5EC0DAGKhJfjo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72223},"main":"dist/index.js","type":"module","_from":"file:bagaking-dma-frame-0.1.0.tgz","types":"dist/index.d.ts","module":"dist/index.esm.js","engines":{"node":">=16.0.0"},"scripts":{"dev":"rollup -c -w","lint":"eslint src/**/*.ts","test":"jest","build":"rollup -c","clean":"rimraf dist","example":"cd examples/height-test && pnpm run start","typecheck":"tsc --noEmit","test:watch":"jest --watch","build:watch":"rollup -c -w","example:dev":"concurrently \"pnpm run build:watch\" \"cd examples/height-test && pnpm run start\"","test:example":"cd examples/height-test && pnpm run start"},"_npmUser":{"name":"kinghand","email":"kinghand@foxmail.com"},"_resolved":"/private/var/folders/rn/qkrjflvj0yqbj7dwjxxgx56r0000gn/T/30f94ed4abd7ceddea37d1bc9b475ec6/bagaking-dma-frame-0.1.0.tgz","_integrity":"sha512-GSKiof/RKDy690oPiSI8AdjlNeJyM5Qw73BaS+VO9M2Bw+0vpMcfyRNi94hSObbetPQX8HTCo2Gq0o5TKO7fdQ==","repository":{"url":"git+https://github.com/bagaking/DMAppFrame.git","type":"git"},"_npmVersion":"10.9.0","description":"Unified API for document mini-app frame control - elegant height management for document addons","directories":{},"_nodeVersion":"22.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tslib":"^2.6.2","eslint":"^8.56.0","rimraf":"^5.0.5","rollup":"^4.12.0","ts-jest":"^29.1.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.19","concurrently":"^9.2.1","@rollup/plugin-typescript":"^11.1.6","@typescript-eslint/parser":"^7.0.2","@typescript-eslint/eslint-plugin":"^7.0.2"},"peerDependencies":{"@lark-opdev/block-docs-addon-api":"^0.0.4"},"peerDependenciesMeta":{"@lark-opdev/block-docs-addon-api":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/dma-frame_0.1.0_1756577374959_0.9340891551326909","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bagaking/dma-frame","version":"0.1.1","type":"module","description":"Unified API for document mini-app frame control - elegant height management for document addons","keywords":["feishu","lark","addon","frame","height-control"],"author":{"name":"bagaking","email":"kinghand@foxmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bagaking/DMAppFrame.git"},"homepage":"https://github.com/bagaking/DMAppFrame#readme","bugs":{"url":"https://github.com/bagaking/DMAppFrame/issues"},"main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","publishConfig":{"access":"public"},"engines":{"node":">=16.0.0"},"peerDependencies":{"@lark-opdev/block-docs-addon-api":"^0.0.4"},"peerDependenciesMeta":{"@lark-opdev/block-docs-addon-api":{"optional":true}},"devDependencies":{"@rollup/plugin-typescript":"^11.1.6","@types/jest":"^29.5.12","@types/node":"^20.11.19","@typescript-eslint/eslint-plugin":"^7.0.2","@typescript-eslint/parser":"^7.0.2","concurrently":"^9.2.1","eslint":"^8.56.0","jest":"^29.7.0","rimraf":"^5.0.5","rollup":"^4.12.0","ts-jest":"^29.1.2","tslib":"^2.6.2","typescript":"^5.3.3"},"scripts":{"build":"rollup -c","build:watch":"rollup -c -w","dev":"rollup -c -w","test":"jest","test:watch":"jest --watch","typecheck":"tsc --noEmit","lint":"eslint src/**/*.ts","clean":"rimraf dist","example":"cd examples/height-test && pnpm run start","example:dev":"concurrently \"pnpm run build:watch\" \"cd examples/height-test && pnpm run start\"","test:example":"cd examples/height-test && pnpm run start"},"_id":"@bagaking/dma-frame@0.1.1","_integrity":"sha512-s5bjlgCWeGM1BEh0drFtdgu1rBL4RSgHRxpixRiikFfgUmWDHsXEIKKq5EsVagLhMB0XYoQKYIcJFsGAprGFRA==","_resolved":"/private/var/folders/rn/qkrjflvj0yqbj7dwjxxgx56r0000gn/T/37d669162df5927e1630fdc44836378c/bagaking-dma-frame-0.1.1.tgz","_from":"file:bagaking-dma-frame-0.1.1.tgz","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-s5bjlgCWeGM1BEh0drFtdgu1rBL4RSgHRxpixRiikFfgUmWDHsXEIKKq5EsVagLhMB0XYoQKYIcJFsGAprGFRA==","shasum":"bd2c5f7882187408b7d7e9ec8fa2fa740d1384bf","tarball":"https://registry.npmjs.org/@bagaking/dma-frame/-/dma-frame-0.1.1.tgz","fileCount":14,"unpackedSize":80772,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCpzjDZASb5YA1hyUce7iLiV5UeC+WiPjuu+kOxUgZ8mAIhAIioeenKlTyI1PNAf9RkLubHHiAp14dXZboDQpNrtb2/"}]},"_npmUser":{"name":"kinghand","email":"kinghand@foxmail.com"},"directories":{},"maintainers":[{"name":"kinghand","email":"kinghand@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dma-frame_0.1.1_1756577996755_0.6702493543183805"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-30T18:09:34.846Z","modified":"2025-08-30T18:19:57.124Z","0.1.0":"2025-08-30T18:09:35.133Z","0.1.1":"2025-08-30T18:19:56.931Z"},"bugs":{"url":"https://github.com/bagaking/DMAppFrame/issues"},"author":{"name":"bagaking","email":"kinghand@foxmail.com"},"license":"MIT","homepage":"https://github.com/bagaking/DMAppFrame#readme","keywords":["feishu","lark","addon","frame","height-control"],"repository":{"type":"git","url":"git+https://github.com/bagaking/DMAppFrame.git"},"description":"Unified API for document mini-app frame control - elegant height management for document addons","maintainers":[{"name":"kinghand","email":"kinghand@foxmail.com"}],"readme":"# @bagaking/dma-frame\n\n> Elegant, unified API for document mini-app frame control\n\nA lightweight, type-safe library providing intelligent height management for document addons, specifically designed for Feishu/Lark platform integration.\n\n## 📋 Status\n\n- **Version**: 0.1.0  \n- **Stability**: Beta  \n- **Platform**: Feishu/Lark Docs Addon  \n- **TypeScript**: Full Support\n\n## ✨ Features\n\n- **🎯 First Principles Design**: Single interface, atomic operations\n- **🔧 Platform Agnostic**: Clean abstraction layer supporting multiple platforms  \n- **⚡ Intelligent Timing**: Smart expand/shrink strategies for optimal UX\n- **🛡️ Type Safe**: Full TypeScript support with comprehensive error handling\n- **🪶 Lightweight**: Zero dependencies except peer dependencies\n- **🧪 Testable**: Built-in mock utilities for easy testing\n\n## 📦 Installation\n\n```bash\nnpm install @bagaking/dma-frame\n```\n\n### Peer Dependencies\n\n```bash\nnpm install @lark-opdev/block-docs-addon-api\n```\n\n## 🚀 Quick Start\n\n### Basic Usage\n\n```typescript\nimport { createFeishuHeightController } from '@bagaking/dma-frame';\n\n// Create controller (automatically handles peer dependency)\nconst controller = await createFeishuHeightController();\n\n// Adjust height with intelligent timing strategies\nawait controller.adjustHeight({\n  targetHeight: 600,\n  onUIChange: () => {\n    // Called immediately for expanding, or before bridge call for shrinking\n    setHeight(600);\n  },\n  onUIComplete: async () => {\n    // Called after bridge call for expanding, or before bridge call for shrinking\n    await animateContent();\n  }\n});\n```\n\n### Advanced Usage\n\n```typescript\nimport { \n  createFeishuBridge, \n  CoreHeightController,\n  type HeightAdjustmentBehavior \n} from '@bagaking/dma-frame';\n\n// Create custom controller with debugging\nconst bridge = await createFeishuBridge({ debug: true });\nconst controller = new CoreHeightController(bridge, true);\n\n// Multiple height adjustments are automatically queued and serialized\nconst behaviors: HeightAdjustmentBehavior[] = [\n  { targetHeight: 400, onUIChange: () => setCompactMode(true) },\n  { targetHeight: 800, onUIChange: () => setExpandedMode(true) }\n];\n\nawait Promise.all(\n  behaviors.map(behavior => controller.adjustHeight(behavior))\n);\n```\n\n### React Integration\n\n```typescript\nimport { useEffect, useRef, useCallback } from 'react';\nimport { createFeishuHeightController, type HeightController } from '@bagaking/dma-frame';\n\nfunction useFrameController() {\n  const controllerRef = useRef<HeightController>();\n\n  useEffect(() => {\n    createFeishuHeightController({ \n      debug: process.env.NODE_ENV === 'development' \n    })\n    .then(controller => {\n      controllerRef.current = controller;\n    })\n    .catch(error => {\n      console.error('Failed to create height controller:', error);\n    });\n\n    return () => controllerRef.current?.dispose();\n  }, []);\n\n  const adjustHeight = useCallback(async (targetHeight: number) => {\n    if (!controllerRef.current || controllerRef.current.isDisposed) return;\n    \n    await controllerRef.current.adjustHeight({\n      targetHeight,\n      onUIChange: () => {\n        // React state updates happen here\n        setCurrentHeight(targetHeight);\n      }\n    });\n  }, []);\n\n  return { adjustHeight };\n}\n```\n\n## 🎛️ API Reference\n\n### Core Interfaces\n\n#### `HeightController`\n\n```typescript\ninterface HeightController {\n  adjustHeight(behavior: HeightAdjustmentBehavior): Promise<void>;\n  dispose(): void;\n  readonly isDisposed: boolean;\n}\n```\n\n#### `HeightAdjustmentBehavior`\n\n```typescript\ninterface HeightAdjustmentBehavior {\n  readonly targetHeight: number;\n  readonly onUIChange?: () => void | Promise<void>;\n  readonly onUIComplete?: () => void | Promise<void>;\n}\n```\n\n### Factory Functions\n\n#### `createFeishuHeightController(options?)`\n\nCreates a complete height controller for Feishu platform.\n\n```typescript\nconst controller = await createFeishuHeightController({\n  debug: true, // Enable debug logging\n  platformId: 'my-addon' // Custom platform identifier\n});\n```\n\n#### `createFeishuBridge(options?)`\n\nCreates just the platform bridge for advanced use cases.\n\n#### `createMockHeightController(options?)`\n\nCreates a mock controller for testing.\n\n## 🔧 Platform Support\n\n### Feishu/Lark\n\nFull support via `@lark-opdev/block-docs-addon-api` integration.\n\n### Custom Platforms\n\nImplement the `PlatformBridge` interface:\n\n```typescript\nimport { PlatformBridge, CoreHeightController } from '@bagaking/dma-frame';\n\nclass CustomPlatformBridge implements PlatformBridge {\n  async updateHeight(targetHeight: number): Promise<number> {\n    // Your platform-specific implementation\n    await yourPlatformAPI.setFrameHeight(targetHeight);\n    return targetHeight;\n  }\n}\n\nconst controller = new CoreHeightController(new CustomPlatformBridge());\n```\n\n## 🧪 Testing\n\nBuilt-in mock utilities make testing easy:\n\n```typescript\nimport { createMockHeightController } from '@bagaking/dma-frame';\n\ndescribe('Height Controller', () => {\n  it('should adjust height correctly', async () => {\n    const controller = createMockHeightController({ debug: true });\n    \n    let uiHeight = 0;\n    await controller.adjustHeight({\n      targetHeight: 500,\n      onUIChange: () => { uiHeight = 500; }\n    });\n    \n    expect(uiHeight).toBe(500);\n  });\n});\n```\n\n## 🏗️ Architecture Principles\n\n### First Principles Design\n- **Single Interface**: One `adjustHeight` method handles all complexity\n- **Atomic Operations**: Height changes and UI updates are treated as single transactions\n- **Intelligent Sequencing**: Automatic optimization for expand vs. shrink operations\n\n### Clean Architecture\n- **Platform Abstraction**: `PlatformBridge` interface isolates platform specifics\n- **Dependency Inversion**: Core logic depends on abstractions, not implementations\n- **Single Responsibility**: Each class has one clear purpose\n\n## 📄 License\n\nMIT © bagaking\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n**Built with ❤️ for better document addon experiences**","readmeFilename":"README.md"}