goey-toast 0.4.1 → 0.5.0

package/README.md

@@ -44,6 +44,24 @@ npx shadcn@latest add https://goey-toast.vercel.app/r/goey-toaster.json
 
 This installs a thin wrapper component at `components/ui/goey-toaster.tsx` and auto-installs the `goey-toast` and `framer-motion` packages.
 
+### AI Agents (Skill)
+
+goey-toast ships a bundled [Agent Skill](https://www.skills.sh/) (`SKILL.md`) so coding agents (Claude Code, Cursor, etc.) know how to install and use it correctly — the required `<GooeyToaster />` mount, the `styles.css` import, and the full API.
+
+Install from the skills.sh registry:
+
+```bash
+npx skills add anl331/goey-toast
+```
+
+Or copy the skill into your project from the package itself:
+
+```bash
+npx goey-toast add-skill            # -> .claude/skills/goey-toast/SKILL.md
+npx goey-toast add-skill --agents   # also append an AGENTS.md pointer
+npx goey-toast add-skill --dir .cursor/skills/goey-toast
+```
+
 ### Peer Dependencies
 
 goey-toast requires the following peer dependencies:

package/bin/cli.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// goey-toast CLI — install the agent skill into a project so coding agents
+// (Claude Code, Cursor, etc.) know how to install and use goey-toast.
+//
+// Usage:
+//   npx goey-toast add-skill            # -> ./.claude/skills/goey-toast/SKILL.md
+//   npx goey-toast add-skill --agents   # also write ./AGENTS.md pointer
+//   npx goey-toast add-skill --dir .codex/skills
+//   npx goey-toast print-skill          # print SKILL.md to stdout
+
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+import {
+  mkdirSync,
+  copyFileSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILL_SRC = resolve(__dirname, '..', 'skills', 'goey-toast', 'SKILL.md')
+
+const argv = process.argv.slice(2)
+const cmd = argv[0]
+
+function getFlag(name) {
+  const i = argv.indexOf(`--${name}`)
+  if (i === -1) return undefined
+  const next = argv[i + 1]
+  return next && !next.startsWith('--') ? next : true
+}
+
+function readSkill() {
+  if (!existsSync(SKILL_SRC)) {
+    console.error(`goey-toast: skill source not found at ${SKILL_SRC}`)
+    process.exit(1)
+  }
+  return readFileSync(SKILL_SRC, 'utf8')
+}
+
+function addSkill() {
+  const dir = typeof getFlag('dir') === 'string'
+    ? getFlag('dir')
+    : '.claude/skills/goey-toast'
+  const dest = resolve(process.cwd(), dir)
+  mkdirSync(dest, { recursive: true })
+  const out = join(dest, 'SKILL.md')
+  copyFileSync(SKILL_SRC, out)
+  console.log(`✓ goey-toast skill installed: ${out}`)
+
+  if (getFlag('agents')) {
+    const agentsPath = resolve(process.cwd(), 'AGENTS.md')
+    const pointer =
+      '\n## goey-toast\n\n' +
+      `See \`${dir}/SKILL.md\` for how to install and use goey-toast ` +
+      '(gooey morphing React toasts). Mount `<GooeyToaster />` once and ' +
+      "import `'goey-toast/styles.css'` at the app entry.\n"
+    if (existsSync(agentsPath)) {
+      const cur = readFileSync(agentsPath, 'utf8')
+      if (!cur.includes('## goey-toast')) {
+        writeFileSync(agentsPath, cur.trimEnd() + '\n' + pointer)
+        console.log(`✓ appended goey-toast pointer to ${agentsPath}`)
+      } else {
+        console.log('• AGENTS.md already references goey-toast — skipped')
+      }
+    } else {
+      writeFileSync(agentsPath, '# AGENTS.md\n' + pointer)
+      console.log(`✓ created ${agentsPath}`)
+    }
+  }
+
+  console.log('\nNext: restart your agent so it picks up the new skill.')
+}
+
+function help() {
+  console.log(`goey-toast CLI
+
+Commands:
+  add-skill              Install the agent skill into ./.claude/skills/goey-toast
+    --dir <path>         Custom target dir (e.g. .codex/skills, .cursor/skills)
+    --agents             Also add/append an AGENTS.md pointer
+  print-skill            Print SKILL.md to stdout
+  help                   Show this help
+
+Examples:
+  npx goey-toast add-skill
+  npx goey-toast add-skill --agents
+  npx goey-toast add-skill --dir .cursor/skills/goey-toast
+`)
+}
+
+switch (cmd) {
+  case 'add-skill':
+    addSkill()
+    break
+  case 'print-skill':
+    process.stdout.write(readSkill())
+    break
+  case undefined:
+  case 'help':
+  case '--help':
+  case '-h':
+    help()
+    break
+  default:
+    console.error(`goey-toast: unknown command "${cmd}"\n`)
+    help()
+    process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goey-toast",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A gooey, morphing toast component built on Sonner with Framer Motion animations",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,8 +18,13 @@
     "*.css"
   ],
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "bin"
   ],
+  "bin": {
+    "goey-toast": "bin/cli.mjs"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/skills/goey-toast/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: goey-toast
+description: Install and use goey-toast — a gooey, morphing React toast component built on Sonner with Framer Motion. Use when adding toast/notification UI to a React app (success/error/warning/info/promise toasts), or when the user mentions goey-toast / gooey toast.
+license: MIT
+---
+
+# goey-toast
+
+A gooey, morphing React toast component built on Sonner with Framer Motion
+animations (pill → blob → pill). Use this skill to install the package and write
+correct usage code in any React project.
+
+## When to use
+
+- Adding toast / notification UI to a React app (React >= 18).
+- The user mentions "goey-toast", "gooey toast", or wants animated/morphing toasts.
+- Replacing raw `sonner` toasts with the gooey variant.
+
+## Install
+
+```bash
+npm install goey-toast react react-dom framer-motion
+```
+
+Peer deps (must exist in the host app):
+
+| Package       | Version   |
+| ------------- | --------- |
+| react         | >= 18.0.0 |
+| react-dom     | >= 18.0.0 |
+| framer-motion | >= 10.0.0 |
+
+### shadcn/ui projects
+
+```bash
+npx shadcn@latest add https://goey-toast.vercel.app/r/goey-toaster.json
+```
+
+Installs a wrapper at `components/ui/goey-toaster.tsx` and auto-installs deps.
+
+## Two required steps to render toasts
+
+1. **Mount `<GooeyToaster />` once** near the app root.
+2. **Import the stylesheet once** at the entry point. Without it toasts render
+   unstyled.
+
+```tsx
+import { GooeyToaster, gooeyToast } from 'goey-toast'
+import 'goey-toast/styles.css' // REQUIRED — import once at app entry
+
+function App() {
+  return (
+    <>
+      <GooeyToaster position="bottom-right" />
+      <button onClick={() => gooeyToast.success('Saved!')}>Save</button>
+    </>
+  )
+}
+```
+
+## API: `gooeyToast`
+
+```ts
+gooeyToast(title, options?)         // default (neutral)
+gooeyToast.success(title, options?) // green
+gooeyToast.error(title, options?)   // red
+gooeyToast.warning(title, options?) // yellow
+gooeyToast.info(title, options?)    // blue
+gooeyToast.promise(promise, data)   // loading → success/error
+gooeyToast.update(id, options)      // update an existing toast in-place
+gooeyToast.dismiss(idOrFilter?)     // dismiss one, by type, or all
+```
+
+### Common options (2nd arg)
+
+| Option          | Type                | Notes                                          |
+| --------------- | ------------------- | ---------------------------------------------- |
+| `description`   | `ReactNode`         | String or component body                       |
+| `action`        | `GooeyToastAction`  | `{ label, onClick, successLabel? }`            |
+| `icon`          | `ReactNode`         | Custom icon (`null` clears in `update`)        |
+| `duration`      | `number`            | ms                                             |
+| `id`            | `string \| number`  | Stable id (needed for `update`)                |
+| `fillColor` / `borderColor` / `borderWidth` | colors / px | Blob styling                  |
+| `spring` / `bounce` | `boolean` / `number` | bounce `0.05`–`0.8`, default `0.4`        |
+| `preset`        | `'smooth' \| 'bouncy' \| 'subtle' \| 'snappy'` | Animation preset    |
+| `showProgress`  | `boolean`           | Countdown bar                                  |
+| `showTimestamp` | `boolean`           | Default `true`                                 |
+| `onDismiss` / `onAutoClose` | `(id) => void` | Dismiss callbacks                    |
+
+### `<GooeyToaster />` key props
+
+`position` (`'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right'`, default `'bottom-right'`),
+`theme` (`'light'|'dark'`), `closeButton`, `showProgress`, `closeOnEscape`,
+`maxQueue`, `queueOverflow` (`'drop-oldest'|'drop-newest'`), `dir` (`'ltr'|'rtl'`),
+`spring`, `bounce`, `preset`, `swipeToDismiss`, `showTimestamp`, `gap`, `offset`.
+
+## Recipes
+
+### Description + action button
+
+```tsx
+gooeyToast.info('Share link ready', {
+  description: 'Your link has been generated.',
+  action: {
+    label: 'Copy',
+    onClick: () => navigator.clipboard.writeText(url),
+    successLabel: 'Copied!', // morphs back to pill after click
+  },
+})
+```
+
+### Promise toast
+
+```tsx
+gooeyToast.promise(saveData(), {
+  loading: 'Saving...',
+  success: (data) => `Saved ${data.count} items`,
+  error: (e) => `Failed: ${String(e)}`,
+  description: { success: 'All changes synced.', error: 'Try again later.' },
+  action: { error: { label: 'Retry', onClick: () => retry() } },
+})
+```
+
+### Update in place
+
+```tsx
+const id = gooeyToast('Uploading...', { icon: <Spinner /> })
+gooeyToast.update(id, { title: 'Done', type: 'success', icon: null })
+```
+
+### Dismiss by filter
+
+```tsx
+gooeyToast.dismiss(id)                       // one
+gooeyToast.dismiss({ type: 'error' })        // all errors
+gooeyToast.dismiss({ type: ['error','warning'] })
+gooeyToast.dismiss()                         // all
+```
+
+## Gotchas
+
+- Forgetting `import 'goey-toast/styles.css'` → unstyled toasts. Most common bug.
+- `<GooeyToaster />` must be mounted exactly once, near the root.
+- `update()` requires the same `id` returned from the create call.
+- `framer-motion` is a peer dep — install it explicitly.
+- Backward-compat aliases exist (`GoeyToaster`, `goeyToast`) for v0.2.x; prefer
+  the double-`o` names (`GooeyToaster`, `gooeyToast`).
+
+## Reference
+
+- Live demo & docs: https://goey-toast.vercel.app
+- npm: https://www.npmjs.com/package/goey-toast