{"id":15283989,"url":"https://github.com/yahoo/ember-power-calendar-selectors","last_synced_at":"2025-04-12T23:20:51.675Z","repository":{"id":48095959,"uuid":"201532025","full_name":"yahoo/ember-power-calendar-selectors","owner":"yahoo","description":"Ember Power Calendar Selectors Addon","archived":false,"fork":false,"pushed_at":"2023-07-06T20:07:55.000Z","size":587,"stargazers_count":4,"open_issues_count":0,"forks_count":5,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-10T09:54:16.292Z","etag":null,"topics":["addon","ember","ember-power-calendar","emberjs","javascript","library","power-calendar","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":"Code-of-Conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-09T19:54:46.000Z","updated_at":"2022-12-13T00:30:00.000Z","dependencies_parsed_at":"2023-01-28T03:46:02.073Z","dependency_job_id":null,"html_url":"https://github.com/yahoo/ember-power-calendar-selectors","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fember-power-calendar-selectors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fember-power-calendar-selectors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fember-power-calendar-selectors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fember-power-calendar-selectors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/ember-power-calendar-selectors/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248644044,"owners_count":21138547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["addon","ember","ember-power-calendar","emberjs","javascript","library","power-calendar","web"],"created_at":"2024-09-30T14:48:32.204Z","updated_at":"2025-04-12T23:20:51.650Z","avatar_url":"https://github.com/yahoo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ember-power-calendar-selectors [![Build Status](https://api.travis-ci.org/yahoo/ember-power-calendar-selectors.svg?branch=master)](https://travis-ci.org/yahoo/ember-power-calendar-selectors)\n\u003e Provides additional date selection components for [`ember-power-calendar`](https://ember-power-calendar.com/)\n\nThis project provides alternative date selection components that integrate with ember-power-calendar \nseamlessly.  Currently a months selector (for selecting over years) and a years selector (for \nselecting over decades) are implemented.\n\n## Table of Content\n\n- [Background](#background)\n- [Install](#install)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Security](#security)\n- [API](#api)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Background\n\n`ember-power-calendar-selectors` was created to allow for more natural selection of dates in the month, quarter, and year\ntime grains.  It only uses the `ember-power-calendar` public API via the yeilded `calendar` object.\n\n## Install\n\nFirst install [`ember-cli-less`](https://github.com/gpoitch/ember-cli-less) or [`ember-cli-sass`](https://github.com/adopted-ember-addons/ember-cli-sass), `ember-power-calendar`, and \n`ember-power-calendar-selectors`\n```shell\nember install ember-cli-less ember-power-calendar ember-power-calendar-selectors\n```\n\nNext import the required styles.\n\nfor example in `app/styles/app.less`\n```less\n@import \"ember-power-calendar\";\n@import \"ember-power-calendar-selectors\";\n\n.ember-power-calendar {\n  .ember-power-calendar(@cell-size: 50px);\n  .ember-power-calendar-selectors(@cell-size: 50px);\n}\n```\n\nor in `app/styles/app.scss`\n```scss\n@import \"ember-power-calendar\";\n@import \"ember-power-calendar-selectors\";\n\n.ember-power-calendar {\n  @include ember-power-calendar($cell-size: 50px);\n  @include ember-power-calendar-selectors($cell-size: 50px);\n}\n```\n\nThe above will style all `.ember-power-calendar`s the same, feel free to \nuse custom class names.\n\n## Configuration\n\nBeyond [Installation](#install), this project does not require other config.  Various scss variables can be set\non the ember power calendar selectors mixin to change it the selector's look and feel if desired.\n\n## Usage\n\nUsage of `ember-power-calendar-selectors` components is nearly the same as the default `ember-power-calendar`\n`calendar.days` component.  The main difference is that the `calendar` object yielded by `power-calendar` must\nbe passed into the new `ember-power-calendar-selectors` selection components.\n\nFor example, here is an example of how to render a non-interactive years selector.\n```hbs\n\u003cPowerCalendar as |calendar|\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\n\nFor more details see the [API](#api).\n\n## Security\n\nThis project doesn't have any security concerns. \n\n## API\n\n### Years Selector\nThe `ember-power-calendar-selectors` addon provides the `power-calendar-months`, and `power-calendar-years` selector\ncomponents which work similarly to the `power-calendar`'s native `calendar.days` yielded component.  It renders selectors for all the years in a decade.\n\nFor example, here is an example of how to render a non-interactive years selector.\n```hbs\n\u003cPowerCalendar as |calendar|\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\n\nWhen an `onSelect` handler is provided to `power-calendar` the `power-calendar-years` selector becomes interactive and sends events to the handler.\n```hbs\n\u003cPowerCalendar \n  @selected={{selected}}\n  @onSelect={{action (mut selected) value=\"date\"}}\n  as |calendar|\n\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\n\nAll the options implemented by `calendar.days` have been reimplemented by `power-calendar-years` as well.  For example,\n```hbs\n\u003cPowerCalendar \n  @selected={{selected}}\n  @onSelect={{action (mut selected) value=\"date\"}}\n  @minRange={{\"2y\"}}\n  @maxRange={{\"5y\"}}\n  as |calendar|\n\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\nworks as expected.  Be advised, `{min,max}Range` interpret `Number` values as days, no matter the subcomponent being rendered.  Pass in `\"{number of years}y\"` if the range should be specified in years as shown above.\n\nAlso, selectors can be used in concert without issue.  For instance,\n```hbs\n\u003cPowerCalendar \n  @selected={{selected}}\n  onSelect={{action (mut selected) value=\"date\"}}\n  @minRange={{\"2y\"}}\n  @maxRange={{\"5y\"}}\n  as |calendar|\n\u003e\n  \u003ccalendar.days /\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\nwill work without a problem.\n\nFinally, selector behavior has been implemented for all the `power-calendar` selection modes, single, range, and multiple. This,\n```hbs\n\u003cPowerCalendarRange\n  @selected={{selected}}\n  @onSelect={{action (mut selected) value=\"date\"}}\n  as |calendar|\n\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendarRange\u003e\n```\nwill work without further tweaking, as will `power-calendar-multiple`.\n\n### Months Selector\nThe `power-calendar-months` component renders with selectors for the 12 months in a year and the quarters by default. It shares most of its API with `power-calendar-years` with a few notable exceptions.\n\n#### `fisrtQuarter`\n`firstQuarter` specifies the starting label of the first quarter. Defaults to `1`.\n```hbs\n\u003cPowerCalendar\n  @selected={{selected}}\n  @onSelect={{action (mut selected) value=\"date\"}}\n  as |calendar|\n\u003e\n  \u003cPowerCalendarMonths @firstQuarter={{2}} @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\nwill render with the first quarter of the year as Q2.\n\n#### `showQuarters`\nDetermines if the quarters should be rendered.  Defaults `true`.\n```hbs\n\u003cPowerCalendar\n  @selected={{selected}}\n  @onSelect={{action (mut selected) value=\"date\"}}\n  as |calendar|\n\u003e\n  \u003cPowerCalendarMonths @showQuarters={{false}} @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\nwill not render with quarters, only months.\n\n\n### Selectors Nav\nIt also provides the `power-calendar-selectors-nav` component.  This component can\nbe used as a more convenient nav for the months, and years selector.\n\nFor example, `power-calendar-selectors-nav` can be used to  navigate by decade instead of\nmonth, convenient when using the years selector.  The `dateFormat` property can be used to \nprovide custom date format strings.  We use [moment.js format strings](https://momentjs.com/docs/#/parsing/string-formats/).\n```hbs\n\u003cPowerCalendar \n  @onCenterChange={{action (mut center) value=\"date\"}}\n  @center={{center}}\n  as |calendar|\n\u003e\n  \u003cPowerCalendarSelectorsNav @dateFormat=\"Today is the Do of MMMM\" @calendar={{calendar}} @by=\"decade\" /\u003e\n  \u003cPowerCalendarYears @calendar={{calendar}} /\u003e\n\u003c/PowerCalendar\u003e\n```\n\n### onSelect Handler\n\nAll default behaviors can be handled through the power-calendar `onSelect` handler hook, just as in base ember power calendar.  For instance,\n\n```hbs\n\u003cPowerCalendarRange \n  @onSelect={{action (mut selected)}}\n  @selected={{selected}}\n  as |cal|\n\u003e\n  \u003cPowerCalendarMonths @calendar={{cal}} /\u003e\n\u003c/PowerCalendarRange\u003e\n```\n\nWill now properly select the entire quarter range when a quarter is selected by the user.\n\nMost users should have no issue using the default behavior provided by the ember-power-calendar actions.  However, the child selector `onSelect` will directly pass the user the selected dateObj allowing them full control of what is selected if the user requires it.  Because of this the child `onSelect` hook has different behavior that the parent component's on `onSelect` hook.\n\nIn the case that the user desires to discriminate between month and quarter selections, the child `onSelect` can be leveraged.\n```hbs\n\u003cPowerCalendarMultiple @selected={{selected}} as |cal|\u003e\n  \u003cPowerCalendarMonths \n    @onSelect={{action \"handleSelect\"}}\n    @calendar={{cal}}\n  /\u003e\n\u003c/PowerCalendarMultiple\u003e\n```\n\n```javascript\n{ actions: {\n  handleSelect(dateObj) {\n    if (dateObj.period === 'quarter') console.log('you clicked a quarter');\n    if (dateObj.period === 'month') console.log('you clicked a month');\n  }\n} }\n```\n\nIn the case that both hooks are used all registered handlers fire in order of specificity.\n```hbs\n\u003cPowerCalendarRange \n  @onSelect={{action (mut selected)}}\n  {{!-- ^fires second --}}\n  @selected={{selected}}\n  as |cal|\n\u003e\n  \u003cPowerCalendarMonths \n    @onSelect={{action (mut selected)}}\n    {{!-- ^fires first --}}\n    @calendar={{cal}}\n  /\u003e\n\u003c/PowerCalendarRange\u003e\n```\n\n## Contribute\n\nPlease refer to [the contributing.md file](Contributing.md) for information about how to get involved. We welcome issues, questions, and pull requests. Pull Requests are welcome.\n\n## Maintainers\n\nAlex Aralis: alex.aralis@verizonmedia.com\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fember-power-calendar-selectors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Fember-power-calendar-selectors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fember-power-calendar-selectors/lists"}