{"_id":"@crescendolab/reamgif","name":"@crescendolab/reamgif","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@crescendolab/reamgif","version":"0.0.1","description":"A template for developing libraries","type":"module","main":"dist/index.js","types":"dist/index.d.ts","dependencies":{"@emotion/css":"^11.13.5","es-toolkit":"^1.39.7","merge-refs":"^2.0.0"},"devDependencies":{"@mui/types":"^7.4.6","@types/react":"^19.1.6","react":"^19.1.0","tsdown":"^0.12.5"},"publishConfig":{"access":"public"},"LICENSE":"Apache-2.0","scripts":{"build":"tsdown"},"_id":"@crescendolab/reamgif@0.0.1","_integrity":"sha512-oXALlsnpPutB3qOTBNkwyZn2ghZ7TSdQSRtIvsnhEaYT687FHvrif4MYv4gIlR/DTCTvICjhJij/+R5qbv1Edw==","_resolved":"/private/var/folders/lp/mvh88q6n7mgfcz5j3mnvx2300000gn/T/4688f533e09aec29a78887de2b7175f4/crescendolab-reamgif-0.0.1.tgz","_from":"file:crescendolab-reamgif-0.0.1.tgz","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-oXALlsnpPutB3qOTBNkwyZn2ghZ7TSdQSRtIvsnhEaYT687FHvrif4MYv4gIlR/DTCTvICjhJij/+R5qbv1Edw==","shasum":"aac8c4c7b7c62fc3dede8499f17c5b8ae46dab88","tarball":"https://registry.npmjs.org/@crescendolab/reamgif/-/reamgif-0.0.1.tgz","fileCount":64,"unpackedSize":256139,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDvRGNPssAC3gPyva8tOqYljSqXC2/oKyBmbRyQafxjPQIhAI0Gk3cAX0oE0r2gb20NOLQVmyQVP//W061hERjakF0Z"}]},"_npmUser":{"name":"vdustr","email":"VdustR@gmail.com"},"directories":{},"maintainers":[{"name":"vdustr","email":"VdustR@gmail.com"},{"name":"joseph_chang_tw","email":"k7451797@gmail.com"},{"name":"jacklee814","email":"jacklee82814@gmail.com"},{"name":"yunchao","email":"yunchao@cresclab.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/reamgif_0.0.1_1757840273708_0.36508942624456897"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-14T08:57:53.617Z","0.0.1":"2025-09-14T08:57:53.940Z","modified":"2025-09-14T08:57:54.255Z"},"maintainers":[{"name":"vdustr","email":"VdustR@gmail.com"},{"name":"joseph_chang_tw","email":"k7451797@gmail.com"},{"name":"jacklee814","email":"jacklee82814@gmail.com"},{"name":"yunchao","email":"yunchao@cresclab.com"}],"description":"A template for developing libraries","readme":"# 🌟 crescendolab-open/reamgif\n\n> [!WARNING]\n> Status: Early preview (APIs may evolve). Feedback & issues welcome.\n\n🎨 ➡️ ⚛️\n\n> Figma‑compatible styling primitives for React components — powered by `@emotion/css`, strongly typed, composable, and friendly with any UI kit (e.g. `react-aria-components`).\n\n`@crescendolab/reamgif` is an experimental foundations layer to let you bring Figma design tokens & per‑element visual props (starting with `cornerRadius`) directly into React without building a giant theme object first. Each prop becomes immediate runtime styles with deterministic precedence while remaining type‑safe and easily overridable.\n\n## ✨ Goals\n\n- 1:1 mental mapping with Figma surface-level properties (radius → `cornerRadius`, more coming: spacing, shadows, variables, semantic tokens)\n- Zero-config emotion instance by default, but overrideable via provider\n- Strong TypeScript inference for polymorphic components (`component` prop pattern)\n- Props-first styling precedence (`css` > `className` > derived styles) with predictable merge\n- Works with any headless/accessibility library (e.g. `react-aria-components`)\n- No runtime theme flattening / no style prop explosion — only explicit supported props\n\n## 🧱 Core Building Blocks\n\n### `ReamgifBox`\n\nFlexible primitive container. Defaults to a `<div>` but can polymorph via the `component` prop. Injects a data attribute (`data-reamgif-box`) for inspection/testing. Combines:\n\n- Default base styles (`display: flex` + label)\n- Derived styles from supported reamgif props (currently `cornerRadius`)\n- User `className`\n- User `css` (highest visual precedence)\n\n```tsx\nimport { ReamgifBox } from \"@crescendolab/reamgif\";\n\nexport function Card() {\n  return (\n    <ReamgifBox\n      cornerRadius={16}\n      css={{ background: \"#18181b\", padding: 24, color: \"white\" }}\n    >\n      Hello Radius\n    </ReamgifBox>\n  );\n}\n```\n\n#### Polymorphic usage\n\n```tsx\n<ReamgifBox component=\"button\" type=\"button\" cornerRadius={8}>\n  Action\n</ReamgifBox>\n```\n\n### `useReamgifProps`\n\nLower-level hook used internally by `ReamgifBox`. You can build your own design primitives with it.\n\nResponsibilities:\n\n- Merges supported visual props (e.g. `cornerRadius`) into an emotion class\n- Computes responsive corner radius (never exceeding half of width/height)\n- Attaches `data-reamgif` marker\n- Merges refs (user + internal) and observes element size using `ResizeObserver` (throttled)\n\n```tsx\nimport { useReamgifProps } from \"@crescendolab/reamgif\";\n\nexport const Panel = ({\n  ref,\n  ...props\n}: { cornerRadius?: number } & {\n  ref?: React.RefObject<HTMLDivElement | null>;\n}) => {\n  const reamgif = useReamgifProps({ ...props, ref });\n  return <div {...reamgif} />;\n};\n```\n\n## 🌀 Styling Precedence\n\n1. `css` prop (emotion interpolation — last word)\n2. `className` prop (user provided)\n3. Derived internal styles (e.g. generated corner radius)\n4. Default base styles (`ReamgifBox.defaultCssInterpolation`)\n\nMerging uses emotion's `css` + `cx` ensuring minimal cascading surprises.\n\n## 🧮 Corner Radius Logic\n\n```txt\neffectiveRadius = clamp(requested, 0, floor(min(width/2, height/2)))\n```\n\nThis prevents oval artifacts when components resize. When the element ref updates, the radius is recalculated (throttled to 300ms by default).\n\n## 🤝 Integrating with Other UI Kits\n\nBecause we only output standard `className` + `data-*` + forwarded props, you can wrap headless/lib components seamlessly:\n\n```tsx\nimport { useReamgifProps } from \"@crescendolab/reamgif\";\nimport { Button } from \"react-aria-components\";\n\nfunction RacButton(\n  props: { cornerRadius?: number } & React.ComponentProps<typeof Button>,\n) {\n  const reamgif = useReamgifProps(props);\n  return <Button {...reamgif} />;\n}\n```\n\nSee Storybook stories under `stories/5_Integration/ReactAriaComponents` for a full example.\n\n## 🛠 Building Your Own Primitive\n\nUse the same pattern as `ReamgifBox`:\n\n```tsx\nimport { useReamgifProps } from \"@crescendolab/reamgif\";\nimport React from \"react\";\n\nexport interface BadgeProps {\n  cornerRadius?: number;\n  tone?: \"neutral\" | \"accent\";\n}\n\nexport const Badge = ({\n  ref,\n  tone = \"neutral\",\n  ...rest\n}: BadgeProps & { ref?: React.RefObject<HTMLSpanElement | null> }) => {\n  const toneCss =\n    tone === \"accent\"\n      ? { background: \"#2563eb\", color: \"white\" }\n      : { background: \"#52525b\", color: \"white\" };\n  const reamgif = useReamgifProps({ ...rest, ref, css: toneCss });\n  return <span {...reamgif} />;\n};\n```\n\n## 📂 Source Structure (Highlights)\n\n```text\npackages/reamgif/src/\n\tReamgifBox.tsx            // Polymorphic primitive\n\tuseReamgifProps.tsx       // Core prop→style bridge\n\tEmotionInstanceProvider.* // (override emotion if needed)\n\tutils.ts                  // helpers (mergeCssInterpolation, etc.)\n```\n\n    > Note: Examples use `React.forwardRef` for compatibility. In React 19+ you can pass `ref` as a normal prop and omit `forwardRef`.\n\n## 🧪 Storybook\n\nExamples live under `packages/sb/stories` grouped by progression:\n\n- 1_Getting_Start – Intro & usage\n- 2_Basic – `ReamgifBox` scenarios\n- 3_Build_Components – Custom component patterns\n- 4_Advanced – Emotion instance provider\n- 5_Integration – Third‑party kit interop\n\nRun locally (in monorepo root):\n\n```bash\npnpm install\npnpm run storybook # (if configured, else check repo scripts)\n```\n\n## 🚀 Install\n\n```bash\npnpm add @crescendolab/reamgif\n# or\nnpm install @crescendolab/reamgif\n# or\nyarn add @crescendolab/reamgif\n```\n\nPeer assumptions: React 18+, modern bundler, CSS capable environment.\n\n## 🔧 Override Emotion Instance\n\nYou can wrap part of the tree with your own emotion cache / insertion logic via `EmotionInstanceProvider` (see advanced story). This allows scoping, SSR control, or shadow-root injection strategies.\n\n## 🗺 Roadmap (Planned)\n\n- Figma-like spacing props (paddingX, gap, etc.)\n- Shadows & blur\n- Design token variables mapping (theme + dynamic runtime)\n- Variant & recipe helpers\n- Improved SSR integration docs\n- Accessibility patterns cookbook\n\n## 🧩 Type System Notes\n\n- Polymorphic prop pattern ensures intrinsic + component props merge safely\n- `cornerRadius` typed as number (future: per-corner granularity)\n- Data attributes: `data-reamgif` (generic), `data-reamgif-box` (box specific)\n\n## 🧪 Testing Strategy (Internal)\n\n- Runtime style precedence snapshots\n- Ref merging & resize observer behavior\n- Radius clamping logic\n\n## 🤔 Why Not Just Tailwind / Styled-System?\n\nReamgif focuses narrowly on mirroring designer mental models (Figma panels) one prop at a time with deterministic merging and minimal abstraction—use it alongside utility classes or design tokens rather than replacing them.\n\n## 📬 Feedback\n\nFile an issue or open a discussion—early ecosystem feedback will shape the API.\n\n---\n\n## 🎯 Release Library\n\nThis repository uses **[changesets/action](https://github.com/changesets/action)**, a GitHub Action that automates release management by creating a pull request with version updates and changelog entries whenever changes are pushed to the `main` branch.\n\nTo enable seamless releases, ensure GitHub Actions have sufficient permissions to write to and manage pull requests in your repository. Navigate to:\n\n**Settings → Code and automation → Actions → General → Workflow permissions** and adjust the following:\n\n- ✅ Select **Read and write permissions**\n- ✅ Enable **Allow GitHub Actions to create and approve pull requests**\n\n## 🤝 Contributing\n\nContributions are welcome! Please read the [contributing guide](https://github.com/crescendolab-open/reamgif/blob/main/CONTRIBUTING.md) for details.\n\n## 📜 License\n\n[Apache-2.0](https://github.com/crescendolab-open/reamgif/blob/main/LICENSE)\n\nCopyright (c) 2025 [Crescendo Lab](https://github.com/crescendolab-open/)\n","readmeFilename":"README.md","_rev":"1-277e5657219b3a63e2065a95529f0024"}