{"id":"biotoxin495/pluginuitoasts","name":"pluginuitoasts","scope":"biotoxin495","platform":"roblox","description":"a small, self-contained toast notification utility built specifically for Roblox Studio plugins.","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"5cd608881c43e9270d96c46a04cc530f78dfecec73e93e8a4d3dc9b8b84ed65a","likes":0,"downloads":0,"install":"forest install biotoxin495/pluginuitoasts","url":"https://forest.dev/p/roblox/biotoxin495/pluginuitoasts","files":"https://api.forest.dev/ai/package/roblox/biotoxin495/pluginuitoasts/files","readme":"# PluginUIToasts — A small toast notification utility for Roblox Studio plugins\n\n**PluginUIToasts** is a small, self-contained toast notification utility built specifically for Roblox Studio plugins.\n\nIt creates and manages its own UI inside any `GuiObject`, displays short-lived status messages for common plugin actions such as saving, publishing, validation, warnings, errors, imports, and exports, and supports Roblox Studio theme changes out of the box.\n\n## Quick example\n\n```lua\nlocal PluginUIToasts = require(script.Parent.PluginUIToasts)\nlocal toasts = PluginUIToasts.new(parentGuiObject)\n\ntoasts:info(\"Scanning assets...\")\ntoasts:success(\"Saved successfully.\")\ntoasts:warning(\"Some items were skipped.\")\ntoasts:danger(\"Failed to save.\")\n```\n\nEvery call returns a toast handle. To dismiss a notification manually instead of waiting for its timer, call `toast:dismiss()`.\n\n## 🚀 Features\n\n* Fully standalone, dependency-free implementation\n* Four built-in notification kinds: `info`, `success`, `warning`, `danger`\n* Simple convenience method for each kind, plus a general-purpose `show`\n* Automatic timed dismissal, with persistent toasts via `duration = 0`\n* Click-to-dismiss on every notification\n* Programmatic dismissal and status queries through toast handles\n* Configurable maximum visible toast count with automatic oldest-toast eviction\n* Roblox Studio Light/Dark theme support with automatic live updates\n* Per-color theme overrides\n* Configurable toast width, height, position, padding, and ZIndex\n* Responsive width inside smaller plugin widgets\n* Automatic cleanup of delayed tasks and event connections\n* Strict Luau types\n\n## 📖 Basic usage\n\nPlace the `PluginUIToasts` ModuleScript somewhere accessible to your plugin code, for example:\n\n```text\nPlugin\n├── Modules\n│   └── PluginUIToasts\n└── Main\n```\n\nPluginUIToasts creates and animates Roblox UI, so it should be given a `GuiObject` that lives inside your plugin's interface.\n\n### Creating a toast manager\n\nPass a `GuiObject` to `PluginUIToasts.new` along with an optional configuration table.\n\n```lua\nlocal toasts = PluginUIToasts.new(parentFrame, {\n\tDefaultDuration = 3,\n\tMaxVisible = 4,\n\tToastWidth = 320,\n\tPosition = \"BottomRight\",\n})\n```\n\nBy default, notifications remain visible for approximately `2.6` seconds and up to `3` can be visible at once.\n\n### Convenience methods\n\nInstead of calling `show()` directly, use the built-in convenience method for each kind:\n\n```lua\ntoasts:info(\"Checking project...\")       -- processing states, background status\ntoasts:success(\"Project saved.\")         -- completed saves, exports, publishes\ntoasts:warning(\"Some assets skipped.\")   -- partial failures, missing optional data\ntoasts:danger(\"Export failed.\")          -- failed operations, invalid states\n```\n\nEach accepts an optional `duration` override:\n\n```lua\ntoasts:success(\"Saved.\", 1.5)\n```\n\n### Toast handles\n\nEvery notification returns a handle that can be queried or dismissed independently.\n\n```lua\nlocal toast = toasts:success(\"Finished.\")\n\nif toast:isActive() then\n\tprint(\"The notification is still visible.\")\nend\n\ntoast:dismiss()\n```\n\nCalling `dismiss()` more than once, or on a toast that has already been removed, is safe.\n\n### Persistent notifications\n\nPassing `0` as the duration creates a notification without an automatic dismissal timer. This is useful for operations whose completion time isn't known ahead of time.\n\n```lua\nlocal toast = toasts:info(\"Exporting...\", 0)\n\nlocal success, result = pcall(performExport)\n\ntoast:dismiss()\n\nif success then\n\ttoasts:success(\"Export complete.\")\nelse\n\ttoasts:danger(\"Export failed.\")\nend\n```\n\nPersistent toasts remain visible until manually dismissed, evicted because of `MaxVisible`, or removed when the manager is destroyed.\n\n### Click-to-dismiss\n\nEvery notification can also be dismissed by clicking anywhere on the toast. No additional configuration is required.\n\n### Customization\n\nMost visual and behavioral aspects of the toast stack can be configured through the options table passed to `PluginUIToasts.new`:\n\n```lua\nlocal toasts = PluginUIToasts.new(parentFrame, {\n\tPosition = \"TopRight\",       -- \"TopLeft\" | \"TopRight\" | \"BottomLeft\" | \"BottomRight\"\n\tPadding = 20,                -- distance from the parent's edges\n\tMaxVisible = 5,              -- oldest toast is evicted once the limit is reached\n\tToastWidth = 340,            -- acts as a maximum width; shrinks in narrow widgets\n\tToastHeight = 60,\n\tZIndex = 500,\n\tUseStudioTheme = true,       -- derive colors from the active Studio theme\n\n\tColors = {\n\t\tsuccess = Color3.fromRGB(80, 220, 120), -- only override what you need\n\t},\n})\n```\n\nCustom `Colors` values always take priority over Studio theme colors, and remain applied even when the user switches Studio themes.\n\n## ⚙️ API\n\n### Manager\n\n#### `PluginUIToasts.new(parent, options?)`\n\nCreates a new toast manager. `parent` is a `GuiObject` that will contain the automatically created toast container; `options` is an optional configuration table (see the [configuration reference](#complete-configuration-reference) below).\n\n```lua\nlocal toasts = PluginUIToasts.new(widgetFrame)\n```\n\n#### `toasts:show(message, kind?, duration?)`\n\nDisplays a notification and returns a toast handle. `kind` defaults to `\"info\"`; `duration` defaults to `DefaultDuration`.\n\n```lua\nlocal toast = toasts:show(\"Plugin settings saved.\", \"success\", 3)\n```\n\n#### `toasts:info(message, duration?)` / `toasts:success(message, duration?)` / `toasts:warning(message, duration?)` / `toasts:danger(message, duration?)`\n\nConvenience wrappers around `show` for each built-in kind.\n\n#### `toasts:dismiss(toast)`\n\nDismisses a toast belonging to this manager. Usually more convenient to call as `toast:dismiss()`.\n\n#### `toasts:dismissAll()`\n\nDismisses every currently active notification.\n\n#### `toasts:destroy()`\n\nDestroys the toast manager and all associated resources: removes every notification, cancels pending lifetime tasks, disconnects click and Studio theme listeners, and destroys the toast container. New notifications cannot be created after this.\n\n### Toast handle\n\n#### `toast:dismiss()`\n\nDismisses the notification. Safe to call more than once.\n\n#### `toast:isActive()`\n\nReturns `true` while the toast is still visible, `false` once it has been dismissed, evicted, or destroyed.\n\n## Complete configuration reference\n\n```lua\nlocal toasts = PluginUIToasts.new(parentFrame, {\n\tColors = {\n\t\tBackground = nil,\n\t\tBorder = nil,\n\t\tText = nil,\n\n\t\tinfo = nil,\n\t\tsuccess = nil,\n\t\twarning = nil,\n\t\tdanger = nil,\n\t},\n\n\tDefaultDuration = 2.6,\n\tMaxVisible = 3,\n\n\tToastHeight = 54,\n\tToastWidth = 300,\n\n\tZIndex = 200,\n\tPadding = 12,\n\n\tUseStudioTheme = true,\n\tPosition = \"BottomRight\",\n})\n```\n\n| Option            | Type       | Default          | Description                                |\n| ----------------- | ---------- | ---------------- | ------------------------------------------ |\n| `Colors`          | `Colors?`  | Theme/default    | Overrides individual toast colors          |\n| `DefaultDuration` | `number`   | `2.6`            | Default toast lifetime, in seconds         |\n| `MaxVisible`      | `number`   | `3`              | Maximum active notifications               |\n| `ToastHeight`     | `number`   | `54`             | Toast height in pixels                     |\n| `ToastWidth`      | `number`   | `300`            | Maximum toast width in pixels              |\n| `ZIndex`          | `number`   | `200`            | Base UI ZIndex                             |\n| `Padding`         | `number`   | `12`             | Distance from the parent's edges           |\n| `UseStudioTheme`  | `boolean`  | `true`           | Uses and monitors the current Studio theme |\n| `Position`        | `Position` | `\"BottomRight\"`  | Corner used for the toast stack            |\n\n## 📝 Notes\n\n* PluginUIToasts is designed for short status messages, not complex interactive notifications — it intentionally has no titles, icons, action buttons, progress bars, notification history, or custom layouts.\n* The complete toast surface acts as its own dismissal target.\n* A zero-duration toast (`duration = 0`) never dismisses itself automatically.\n* `MaxVisible` is a strict limit — the oldest active notification is removed before another is shown.\n* Once a toast is gone, `toast:isActive()` returns `false` and further `toast:dismiss()` calls have no effect.\n* When Studio theme integration is enabled, currently visible notifications update automatically when the active Studio theme changes.\n* PluginUIToasts is intended for client-side plugin UI.\n\n## 🛠️ Installation\n\nPlace `PluginUIToasts` (the ModuleScript folder) somewhere accessible to your plugin — for example:\n\n```text\nPlugin\n├── Modules\n│   └── PluginUIToasts\n└── Main\n```\n\nThen require it from your plugin script:\n\n```lua\nlocal PluginUIToasts = require(script.Parent.Modules.PluginUIToasts)\n```\n\nThe module does not require any other packages or modules.\n\n## License\n\nAdd the license used by your project before publishing the module.\n\n\nmade with ❤️ by biotoxin495\n","readmeTruncated":false}