{"id":"rvila94/simpletoasts","name":"simpletoasts","scope":"rvila94","platform":"roblox","description":"Zero-dependency, PrimeNG-inspired toast notification library for Roblox.","version":"0.2.0","latest":"0.2.0","versions":["0.1.0","0.2.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"9d7bfaab75f752503dcda4c92a7a4bc2418f3b1d1c42f75c7e96bbb1d32ad539","likes":0,"downloads":0,"install":"forest install rvila94/simpletoasts","url":"https://forest.dev/p/roblox/rvila94/simpletoasts","files":"https://api.forest.dev/ai/package/roblox/rvila94/simpletoasts/files","readme":"# SimpleToasts\n\nA zero-dependency, [PrimeNG](https://primeng.org/toast)-inspired **toast notification\nlibrary for Roblox**.\n\n[![CI](https://github.com/rvila94/SimpleToasts/actions/workflows/ci.yml/badge.svg)](https://github.com/rvila94/SimpleToasts/actions/workflows/ci.yml)\n[![Wally](https://img.shields.io/badge/wally-rvila94%2Fsimpletoasts-blue)](https://wally.run/package/rvila94/simpletoasts)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n![SimpleToasts demo](docs/demo.gif)\n\n| Collapsed pile (hover to expand)                        | Expanded pile                                         |\n| ------------------------------------------------------- | ----------------------------------------------------- |\n| ![Collapsed stacked toasts](docs/stacked-collapsed.png) | ![Expanded stacked toasts](docs/stacked-expanded.png) |\n\n## Features\n\n- 🎨 **Five severities** : `success`, `info`, `warn`, `error`, `secondary`, each with\n  its own colours, icon, and sound (optional); fully overridable per toast via `customTheme`.\n- 📍 **Six positions** : `top-left`, `top-center`, `top-right`, `bottom-left`,\n  `bottom-center`, `bottom-right`.\n- 🥞 **Stacked piles** (Sonner-style, on by default) : newest toast in front, older\n  edges peeking behind; hover (desktop) or tap (mobile) expands the pile and pauses\n  every timer in it.\n- ⏱️ **Auto-dismiss** with `life`, `sticky` toasts, close button, and pause-on-hover.\n- 🎬 **Smooth animations** : slide-in/out from the nearest screen edge + fade, with\n  tweenable neighbour reflow; duration and easing are configurable.\n- 🔊 **Sounds** (opt-in) : per-severity defaults, per-toast override (`sound`,\n  `silent`, `volume`), global toggle.\n- 🌐 **Server → client bridge** : fire toasts from the server with `Toast.notify` /\n  `Toast.notifyAll` (display-only; the client never trusts remote data for anything\n  else).\n- 🧱 **Zero dependencies** : native Luau instances only (`CanvasGroup`, `TweenService`,\n  …). No Fusion, Roact, or React-lua. Fully `--!strict` typed.\n\n## Installation\n\n### Wally\n\n```toml\n[dependencies]\nSimpleToasts = \"rvila94/simpletoasts@0.1.0\"\n```\n\nThen run `wally install` and require it from your `Packages` folder.\n\n### Standalone model\n\nBuild a `.rbxm` with [Rojo](https://rojo.space) and drop it anywhere your scripts can\nreach (e.g. `ReplicatedStorage`):\n\n```bash\nrojo build default.project.json -o SimpleToasts.rbxm\n```\n\n## Quick start\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal Toast = require(ReplicatedStorage.Packages.SimpleToasts)\n\n-- Convenience shortcuts: (summary, detail?, options?)\nToast.success(\"Saved!\", \"Your progress has been saved.\")\nToast.info(\"Heads up\")\nToast.warn(\"Storage almost full\", nil, { position = \"bottom-center\" })\nToast.error(\"Something went wrong\", \"Please try again later.\", { life = 8000 })\nToast.secondary(\"Background task finished\")\n```\n\n### Full message form\n\n```lua\nToast.add({\n\tseverity = \"success\",   -- \"success\" | \"info\" | \"warn\" | \"error\" | \"secondary\"\n\tsummary  = \"Title\",\n\tdetail   = \"Optional body text\",\n\tlife     = 4000,        -- ms before auto-dismiss (default: 3000)\n\tsticky   = false,       -- true = never auto-dismiss\n\tclosable = true,        -- show the close button (default: true)\n\tposition = \"top-right\", -- one of the six positions (default: \"top-right\")\n\n\t-- Appearance override (all colours/icon/sound of the severity theme):\n\tcustomTheme = {\n\t\tbackgroundColor = Color3.fromRGB(249, 219, 159),\n\t\taccentColor = Color3.fromRGB(209, 152, 38),\n\t\tdetailTextColor = Color3.fromRGB(30, 30, 30), -- omit for the default dark grey\n\t\ticonAssetId = \"rbxassetid://...\", -- omit to show no icon\n\t},\n\n\t-- Sound (all optional; sounds are off by default, see configure below):\n\tsound  = \"rbxassetid://...\", -- plays even when soundEnabled = false\n\tsilent = false,              -- true = suppress sound for this toast\n\tvolume = 0.8,                -- 0-1, overrides defaultVolume\n})\n\n-- Several at once:\nToast.addAll({ message1, message2 })\n\n-- Remove every visible toast (optionally only one position):\nToast.clear()\nToast.clear(\"bottom-right\")\n```\n\n### From the server\n\n```lua\n-- Fire a toast to one player, or to everyone:\nToast.notify(player, { severity = \"success\", summary = \"Welcome!\" })\nToast.notifyAll({ severity = \"info\", summary = \"Server restart in 5 minutes\" })\n```\n\nThe bridge is server → client only, created lazily on first use (a `RemoteEvent` in\n`ReplicatedStorage`). The client only ever _displays_ what it receives.\n\n## Configuration\n\n`Toast.configure()` merges overrides into the active config at runtime. Defaults shown:\n\n```lua\nToast.configure({\n\t-- Behaviour\n\tdefaultLife = 3000,            -- ms\n\tdefaultPosition = \"top-right\",\n\tdefaultClosable = true,\n\tmaxVisible = 5,                -- cap per position\n\tdisplayOrder = 1000,           -- ScreenGui DisplayOrder (keeps toasts above game UI)\n\n\t-- Stacked piles\n\tstacked = true,                -- false = classic vertical list\n\texpandedCount = 3,             -- toasts shown when a pile is expanded\n\n\t-- Animation & appearance\n\tanimationDuration = 0.25,      -- seconds per animation phase\n\tanimationEasing = Enum.EasingStyle.Quint,\n\tbackgroundTransparency = 0.08, -- card background (0 = opaque)\n\tfontSize = 14,\n\tfontFace = Font.fromEnum(Enum.Font.Gotham), -- summary text uses its Bold weight\n\n\t-- Sounds\n\tsoundEnabled = false,          -- true = play per-severity sounds automatically\n\tdefaultVolume = 0.5,\n})\n```\n\n### Severity themes\n\n| Severity    | Background | Accent                |\n| ----------- | ---------- | --------------------- |\n| `success`   | `#F0FDF4`  | `#4ADE80` / `#16A34A` |\n| `info`      | `#EFF6FF`  | `#60A5FA` / `#2563EB` |\n| `warn`      | `#FFFBEB`  | `#FBB024` / `#D97706` |\n| `error`     | `#FEF2F2`  | `#F87171` / `#DC2626` |\n| `secondary` | neutral    | neutral               |\n\nEvery theme (colours, icon, sound) can be replaced globally through\n`Toast.configure({ themes = ... })` or per toast with `customTheme`. The\n`themes` table passed to `configure` is merged per severity: severities you\nomit keep their current theme.\n\n## Running the demo\n\nThe repository ships with a keyboard-driven demo place:\n\n```bash\nrojo serve demo.project.json\n```\n\nConnect from Roblox Studio with the Rojo plugin, press Play, then:\n\n| Key                 | Action                                                   |\n| ------------------- | -------------------------------------------------------- |\n| `1`-`6` (or numpad) | success · info · warn · error · secondary · custom theme |\n| `Shift`             | target the **top-right** corner (default)                |\n| `Ctrl`              | target the **bottom-right** corner                       |\n\nThe demo server script also fires a welcome toast to each joining player to exercise\nthe server bridge.\n\n## Development\n\nTooling is pinned with [Rokit](https://github.com/rojo-rbx/rokit):\n\n```bash\nrokit install\n\nselene src demo          # lint\nstylua --check src demo  # formatting\nrojo sourcemap demo.project.json -o sourcemap.json\nluau-lsp analyze --definitions=globalTypes.d.luau --sourcemap=sourcemap.json src demo\n```\n\n(`globalTypes.d.luau` comes from\n[luau-lsp](https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/main/scripts/globalTypes.d.luau).)\n\nAll four checks run in CI on every push and pull request.\n\n## License\n\n[MIT](LICENSE) © rvila94\n","readmeTruncated":false}