{"_id":"@benpley/wappler-star-rating","_rev":"2-49e7f03768899f05880d2028d30cc8a5","name":"@benpley/wappler-star-rating","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@benpley/wappler-star-rating","version":"1.0.0","keywords":["wappler-extension","wappler","appconnect","star-rating","rating","widget","bootstrap5","php","nodejs","asp.net"],"author":{"url":"https://wappler.io/community","name":"Ben Pleysier"},"license":"MIT","_id":"@benpley/wappler-star-rating@1.0.0","maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"dist":{"shasum":"370ebfc3852519e10edc63558fbf04414ade1468","tarball":"https://registry.npmjs.org/@benpley/wappler-star-rating/-/wappler-star-rating-1.0.0.tgz","fileCount":5,"integrity":"sha512-7QQph7OePg+XirZzGkwqf5/GKSe6eX1bmCBEseHAQuo+kspnObAicLu91TmFqk3z15hcxoVGRLX6snsyu5jufg==","signatures":[{"sig":"MEUCIG1AsDw0I785tAJ79nPxREcPNo3th8/6Tzio6JWNcNFLAiEAmMrIJ8uoL2ZuEwcPdxJ0e5XhC1L2ES5jrIJ7HbHf/ZM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":16432},"engines":{"wappler":">=4.0.0"},"_npmUser":{"name":"benpley","email":"ben@pleysier.com.au"},"_npmVersion":"11.12.1","description":"An interactive star rating widget for Wappler App Connect pages.","directories":{},"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/wappler-star-rating_1.0.0_1779834172334_0.11841213041259135","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@benpley/wappler-star-rating","version":"1.0.1","description":"An interactive star rating widget for Wappler App Connect pages with static and dynamic rating values.","author":{"name":"Ben Pleysier","url":"https://wappler.io/community"},"license":"MIT","keywords":["wappler-extension","wappler","appconnect","star-rating","rating","widget","bootstrap5","php","nodejs","asp.net"],"engines":{"wappler":">=4.0.0"},"publishConfig":{"access":"public"},"_id":"@benpley/wappler-star-rating@1.0.1","_nodeVersion":"22.19.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-yOkf/+jqgLFSf03hcz1Gvavvf9XS1RIX2Ahac5oXV6mKXorgo2AA1F3T6ByODXi1KKeW2YS0H5pGsbwurABhyA==","shasum":"96547121e5a4ab6482eadfb6add57e10b5ae6675","tarball":"https://registry.npmjs.org/@benpley/wappler-star-rating/-/wappler-star-rating-1.0.1.tgz","fileCount":5,"unpackedSize":18460,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCztUS1tSKn6dcrMA0l9iGvLgzfYnLRfCoFXOUA7hqCiwIgZgNPaWg2Tx3ucaD+r/L1mDuUEAvHZ8/KZBpIGhWMyZo="}]},"_npmUser":{"name":"benpley","email":"ben@pleysier.com.au"},"directories":{},"maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wappler-star-rating_1.0.1_1779939817900_0.4783349603870899"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-26T22:22:52.168Z","modified":"2026-05-28T03:43:38.139Z","1.0.0":"2026-05-26T22:22:52.464Z","1.0.1":"2026-05-28T03:43:38.034Z"},"author":{"name":"Ben Pleysier","url":"https://wappler.io/community"},"license":"MIT","keywords":["wappler-extension","wappler","appconnect","star-rating","rating","widget","bootstrap5","php","nodejs","asp.net"],"description":"An interactive star rating widget for Wappler App Connect pages with static and dynamic rating values.","maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"readme":"# Wappler Star Rating\n\nAn interactive star rating widget for [Wappler](https://wappler.io) App Connect pages.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Properties](#properties)\n- [Actions](#actions)\n- [Events](#events)\n- [Examples](#examples)\n- [Changelog](#changelog)\n- [License](#license)\n\n---\n\n## Overview\n\n**Wappler Star Rating** adds a fully reactive, accessible star rating widget to your App Connect pages. It works as a native custom element (`<star-rating>`) wrapped in a Wappler App Connect component (`is=\"dmx-star-rating\"`), meaning it integrates seamlessly with App Connect data bindings, actions, and events.\n\nKey features:\n\n- Reactive — bind the current rating to any App Connect data source using Wappler's Dynamic Attributes UI\n- Programmatic control — set the value from any event handler or flow step\n- Read-only mode — render star displays without user interaction\n- Change event — hook into user clicks with `dmx-on:change`\n- Zero dependencies — pure Web Component + App Connect, no third-party libraries\n- Compatible with Bootstrap 5, PHP, Node.js, and ASP.NET Wappler projects\n\n---\n\n## Requirements\n\n| Requirement | Version    |\n|-------------|------------|\n| Wappler     | >= 4.0.0   |\n| App Connect | Any        |\n\n---\n\n## Installation\n\nInstall **Wappler Star Rating** using Wappler's built-in **Extension Manager**:\n\n1. Open Wappler and go to **Extensions → Extension Manager**.\n2. Search for **`wappler-star-rating`** or browse the **Widgets** category.\n3. Click **Install** next to **Wappler Star Rating** by *Ben Pleysier*.\n4. Restart Wappler (or reload your project) when prompted.\n\nThe extension will automatically register the `dmx-star-rating` component, copy `star-rating.js` to your project's `js/` folder, and link it on any page you add the component to.\n\n> **Manual install (advanced):** If you need to install without the Extension Manager, place the package under your project's extension directory and ensure `js/star-rating.js` is linked in the page head.\n\n---\n\n## Usage\n\nAfter installation, insert the **Star Rating** component from the Wappler App Connect panel under the **Widgets** group.\n\nThe generated markup looks like this:\n\n```html\n<star-rating is=\"dmx-star-rating\" id=\"rating1\" rating=\"0\" max=\"5\"></star-rating>\n```\n\nFor static values, set the **Rating** property. For dynamic values, add **Dynamic Attributes → Star Rating → Rating** in Wappler and select the data source for `dmx-bind:rating`.\n\n### Dynamic binding example\n\n```html\n<star-rating\n  is=\"dmx-star-rating\"\n  id=\"product_rating\"\n  dmx-bind:rating=\"sc_product.data.rating\"\n  max=\"5\"\n></star-rating>\n```\n\n### Read-only display example\n\n```html\n<star-rating\n  is=\"dmx-star-rating\"\n  id=\"display_rating\"\n  dmx-bind:rating=\"reviews.average_score\"\n  max=\"5\"\n  readonly\n></star-rating>\n```\n\n---\n\n## Properties\n\n| Property   | Attribute  | Type    | Default | Description                                                     |\n|------------|------------|---------|---------|----------------------------------------------------------------|\n| Id         | `id`       | text    | —       | Unique App Connect component id used in expressions and scopes. |\n| Rating     | `rating`   | number  | `0`     | The current star rating value (0 to max).                      |\n| Max Stars  | `max`      | number  | `5`     | The maximum number of stars to display.                        |\n| Read Only  | `readonly` | boolean | `false` | When enabled the user cannot change the rating.                |\n\nThe **Rating** value supports Wappler's Dynamic Attributes UI and can be bound using `dmx-bind:rating=\"...\"`. The component initializes from the App Connect bound prop, so both static `rating=\"\"` and dynamic `dmx-bind:rating` values are supported.\n\n---\n\n## Actions\n\n| Action       | Parameter           | Type   | Description                              |\n|--------------|---------------------|--------|------------------------------------------|\n| `setValue()` | `value` *(required)*| number | Set the star rating value programmatically. |\n\n**Example — set value from a button click:**\n\n```html\n<button dmx-on:click=\"product_rating.setValue(5)\">Give 5 Stars</button>\n```\n\n**Example — reset rating:**\n\n```html\n<button dmx-on:click=\"product_rating.setValue(0)\">Clear Rating</button>\n```\n\n---\n\n## Events\n\n| Event    | Fires when…                                   |\n|----------|-----------------------------------------------|\n| `change` | The user clicks a star to change the rating.  |\n\nAccess the current value in the event handler via the component's `value` property:\n\n```html\n<star-rating\n  is=\"dmx-star-rating\"\n  id=\"my_rating\"\n  rating=\"0\"\n  max=\"5\"\n  dmx-on:change=\"sc_save.load({ rating: my_rating.value })\"\n></star-rating>\n```\n\n---\n\n## Examples\n\n### Save a rating to the database on change\n\n```html\n<star-rating\n  is=\"dmx-star-rating\"\n  id=\"review_rating\"\n  dmx-bind:rating=\"sc_review.data.rating\"\n  max=\"5\"\n  dmx-on:change=\"sc_update_rating.load({ id: sc_review.data.id, rating: review_rating.value })\"\n></star-rating>\n```\n\n### Show current value as text\n\n```html\n<star-rating is=\"dmx-star-rating\" id=\"my_rating\" rating=\"3\" max=\"5\"></star-rating>\n<p>You rated: <span dmx-text=\"my_rating.value\"></span> / 5</p>\n```\n\n### Read-only average rating from a data source\n\n```html\n<star-rating\n  is=\"dmx-star-rating\"\n  id=\"avg_rating\"\n  dmx-bind:rating=\"sc_stats.data.average_rating\"\n  max=\"5\"\n  readonly\n></star-rating>\n```\n\n---\n\n## Changelog\n\n### v1.0.1 — 2026-05-28\n\n- Added a **Star Rating → Rating** dynamic attribute entry for Wappler's Dynamic Attributes UI.\n- The Rating dynamic attribute writes `dmx-bind:rating=\"...\"` and exposes the App Connect data picker.\n- Updated component initialization to read from the bound App Connect prop (`this.props.rating`), supporting both static `rating=\"\"` and dynamic `dmx-bind:rating` values.\n\n### v1.0.0 — 2026-05-26\n\n- Initial release.\n- Interactive star rating widget built as a Web Component.\n- Full App Connect integration: reactive `rating` and `max` bindings, `readonly` support.\n- `setValue(value)` action for programmatic control.\n- `change` event fired on user interaction.\n- Shadow DOM–based rendering with gold/silver star styling and hover state.\n- MutationObserver-driven sync between the custom element and App Connect state.\n- Compatible with Wappler >= 4.0.0 (Bootstrap 5, PHP, Node.js, ASP.NET).\n\n---\n\n## License\n\n[MIT](./LICENSE.md) © [Ben Pleysier](https://wappler.io/community)\n","readmeFilename":"README.md"}