@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/calendar.json

@@ -0,0 +1,592 @@
+{
+  "family": "calendar",
+  "ui": "calendar",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Month grid for choosing a date or a range."
+  },
+  "axes": {
+    "months": [
+      "1",
+      "2",
+      "3"
+    ],
+    "selectionMode": [
+      "single",
+      "range",
+      "multiple"
+    ],
+    "view": [
+      "day",
+      "month",
+      "year"
+    ],
+    "calendar": [
+      "gregory"
+    ],
+    "weekNumbers": [
+      "off",
+      "on"
+    ],
+    "fixedWeeks": [
+      "off",
+      "on"
+    ],
+    "outsideDays": [
+      "shown",
+      "selectable",
+      "hidden"
+    ]
+  },
+  "members": {
+    "calendar": {
+      "nativeElement": "div",
+      "defaults": {
+        "months": 1,
+        "selectionMode": "single",
+        "view": "day",
+        "calendar": "gregory",
+        "weekNumbers": false,
+        "fixedWeeks": false,
+        "outsideDays": "shown"
+      },
+      "capabilities": [
+        "value",
+        "current",
+        "appearance",
+        "content",
+        "disabled",
+        "readOnly",
+        "invalid",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "selected"
+      ],
+      "parts": [
+        "root",
+        "header",
+        "previous",
+        "next",
+        "heading",
+        "grids",
+        "grid",
+        "grid-caption",
+        "week-headers",
+        "week-header",
+        "week",
+        "week-number",
+        "cell",
+        "day",
+        "months",
+        "years",
+        "period"
+      ]
+    }
+  },
+  "docs": {
+    "calendar": {
+      "imports": {
+        "source": "import { SlCalendar } from '@slotted/angular/calendar';",
+        "selector": "[slCalendar]",
+        "exportAs": "slCalendar"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the consumer’s own element",
+          "required": true,
+          "purpose": "The box everything stands in, and the query container the cell size is measured against. Carries data-ui=\"calendar\", data-view, data-months, data-week-numbers and the state attributes. The consumer writes this element, so its classes, its attributes and its own directives are its own."
+        },
+        {
+          "part": "header",
+          "element": "div",
+          "required": true,
+          "purpose": "The row above the grid: the two page triggers with the heading between them. The heading is between rather than beside, because it is the thing being changed and a label at one end would make the pair read as two unrelated buttons."
+        },
+        {
+          "part": "previous",
+          "element": "button",
+          "required": true,
+          "purpose": "One page back, in whichever view is showing: a month in the day view, a year in the month view, twelve years in the year view. Its chevron is the next trigger’s artwork turned, so both follow the document direction from one token."
+        },
+        {
+          "part": "next",
+          "element": "button",
+          "required": true,
+          "purpose": "One page forward, on the same terms as previous."
+        },
+        {
+          "part": "heading",
+          "element": "button",
+          "required": true,
+          "purpose": "The month and year, and the way up to the month and year views. It is aria-live=\"polite\" because paging with a key changes nothing that focus lands on, so without it nothing announces the new month. It is also what every grid points aria-labelledby at."
+        },
+        {
+          "part": "grids",
+          "element": "div",
+          "required": true,
+          "purpose": "Holds one month or several. They wrap rather than scroll: a month that no longer fits beside another goes under it, and nothing is withdrawn."
+        },
+        {
+          "part": "grid",
+          "element": "table",
+          "required": true,
+          "purpose": "One month, carrying role=\"grid\". The row, columnheader and gridcell roles are implied by tr, th and td and are deliberately not written — the APG’s own note, and the duplication a pattern check refuses."
+        },
+        {
+          "part": "grid-caption",
+          "element": "caption",
+          "required": true,
+          "purpose": "The month’s own name. Out of the picture while one month is drawn, because the heading already shows it; visible once two or three are, because the heading then names the span and nothing else would say where October starts."
+        },
+        {
+          "part": "week-headers",
+          "element": "tr",
+          "required": true,
+          "purpose": "The weekday row, starting on the day the locale starts its week on."
+        },
+        {
+          "part": "week-header",
+          "element": "th",
+          "required": true,
+          "purpose": "One weekday, drawn in the locale’s own narrow form and never truncated. abbr carries the full name, which is the difference between hearing \"Mo\" and hearing \"Monday\"."
+        },
+        {
+          "part": "week",
+          "element": "tr",
+          "required": true,
+          "purpose": "One week of the month."
+        },
+        {
+          "part": "week-number",
+          "element": "th",
+          "required": false,
+          "purpose": "The ISO 8601 week number, as a row header. Narrower than a day and separated by a rule, so it reads as an annotation rather than as an eighth day."
+        },
+        {
+          "part": "cell",
+          "element": "td",
+          "required": true,
+          "purpose": "The grid cell. It carries the facts about the date — data-outside-month, data-unavailable, data-selected, data-range-start, data-range-end, data-in-range — and the range band is painted on it, behind the day."
+        },
+        {
+          "part": "day",
+          "element": "span",
+          "required": true,
+          "purpose": "The number the reader presses. It holds the roving tabindex, data-today, aria-selected and aria-disabled. It is the cell’s child rather than the cell itself because the range band runs edge to edge while the day stays a rounded box inside it."
+        },
+        {
+          "part": "months",
+          "element": "div",
+          "required": false,
+          "purpose": "The month view’s own grid, four across, reached from the heading."
+        },
+        {
+          "part": "years",
+          "element": "div",
+          "required": false,
+          "purpose": "The year view’s own grid, four across and twelve to a page. The page is anchored rather than centred, so the year the reader is on keeps its cell between presses."
+        },
+        {
+          "part": "period",
+          "element": "button",
+          "required": false,
+          "purpose": "One month or one year in those two views."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "PlainDate | DateRange | PlainDate[] | null",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "What the calendar holds, which depends on selectionMode. Present means the consumer owns it."
+        },
+        {
+          "name": "defaultValue",
+          "type": "PlainDate | DateRange | PlainDate[] | null",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "What it starts from when nobody else writes one. Read once; a later change to it is not new state."
+        },
+        {
+          "name": "focusedDate",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "The date the reader is on, which is not the date they have chosen. Present means the consumer owns it, which is what a product that pages a calendar from outside needs."
+        },
+        {
+          "name": "defaultFocusedDate",
+          "type": "PlainDate",
+          "defaultValue": "today",
+          "appliesTo": "SlCalendar",
+          "description": "Where the reader starts. Unset, it is the value if there is one and today if there is not."
+        },
+        {
+          "name": "selectionMode",
+          "type": "'single' | 'range' | 'multiple'",
+          "defaultValue": "single",
+          "appliesTo": "SlCalendar",
+          "description": "How many dates the reader may choose, and what the value then is."
+        },
+        {
+          "name": "months",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "SlCalendar",
+          "description": "How many months are drawn side by side. They wrap when they do not fit; nothing is withdrawn."
+        },
+        {
+          "name": "view",
+          "type": "'day' | 'month' | 'year'",
+          "defaultValue": "day",
+          "appliesTo": "SlCalendar",
+          "description": "Which grid is showing. Present means the consumer owns it; defaultView sets the starting one."
+        },
+        {
+          "name": "defaultView",
+          "type": "'day' | 'month' | 'year'",
+          "defaultValue": "day",
+          "appliesTo": "SlCalendar",
+          "description": "The view it opens on."
+        },
+        {
+          "name": "min",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "The earliest date the reader may reach. An arrow that would leave the range stops at the edge."
+        },
+        {
+          "name": "max",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "The latest date the reader may reach."
+        },
+        {
+          "name": "isDateUnavailable",
+          "type": "(date: PlainDate) => boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Refuses particular dates. A refused date stays focusable and cannot be chosen."
+        },
+        {
+          "name": "weekNumbers",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlCalendar",
+          "description": "Draws the ISO 8601 week number as a row header."
+        },
+        {
+          "name": "fixedWeeks",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlCalendar",
+          "description": "Always six rows, so paging does not change the surface’s height. Worth setting inside a popover."
+        },
+        {
+          "name": "outsideDays",
+          "type": "'shown' | 'selectable' | 'hidden'",
+          "defaultValue": "shown",
+          "appliesTo": "SlCalendar",
+          "description": "What a day of the month either side does: drawn and not pressable, drawn and pressable, or not drawn."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the language in force",
+          "appliesTo": "SlCalendar",
+          "description": "BCP 47. Decides the month names, the weekday names and the day a week starts on."
+        },
+        {
+          "name": "timeZone",
+          "type": "string",
+          "defaultValue": "the runtime’s",
+          "appliesTo": "SlCalendar",
+          "description": "Which zone answers \"what is today\"."
+        },
+        {
+          "name": "firstDayOfWeek",
+          "type": "number",
+          "defaultValue": "the locale’s",
+          "appliesTo": "SlCalendar",
+          "description": "0 is Sunday. Overrides what the locale says, for a product that fixes one."
+        },
+        {
+          "name": "calendar",
+          "type": "'gregory'",
+          "defaultValue": "gregory",
+          "appliesTo": "SlCalendar",
+          "description": "The calendar system. One value today, and an axis rather than a silence."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Answers no key and no press, and takes every cell out of the tab sequence."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Readable and not changeable, and never faded."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Retargets the focus ring to the danger colour."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<CalendarMessages>",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Words laid over the language in force, key by key: the back (previous) and forward (next) triggers’ accessible names."
+        }
+      ],
+      "composition": [
+        {
+          "name": "provideCalendarDefaults",
+          "type": "Provider",
+          "defaultValue": "—",
+          "appliesTo": "application",
+          "description": "Sets timeZone, firstDayOfWeek, months, weekNumbers, fixedWeeks, outsideDays and calendar once for everything under the injector; an input on the calendar still wins."
+        },
+        {
+          "name": "exportAs",
+          "type": "slCalendar",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Hands a template the instance, so focus(), focusDate(), currentView() and the derived selection() signal are reachable without a component of its own."
+        },
+        {
+          "name": "focusDate",
+          "type": "(date: PlainDate) => void",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Moves the reader to a date, paging the grid to reach it — the one action no input can express."
+        },
+        {
+          "name": "currentView",
+          "type": "Signal<CalendarView>",
+          "defaultValue": "—",
+          "appliesTo": "SlCalendar",
+          "description": "Which grid is showing, as a signal, so a template reads it without an event handler and without a second copy of it."
+        }
+      ],
+      "events": [
+        {
+          "name": "valueChange",
+          "payload": "ChangeRequest<CalendarValue>",
+          "when": "Before the value moves, and cancellable. The request carries the new value, the value it replaces, the reason — pointer or keyboard — and the originating event. There is no two-way [(value)]: one slot could carry none of that."
+        },
+        {
+          "name": "focusedDateChange",
+          "payload": "ChangeRequest<PlainDate>",
+          "when": "Before the date the reader is on moves, and cancellable. It fires for every arrow and every page, which is what lets a consumer load a month before it is shown."
+        },
+        {
+          "name": "viewChange",
+          "payload": "CalendarView",
+          "when": "When the heading walks up a view or Escape walks down one."
+        }
+      ],
+      "accessibility": [
+        "The grid role is on a real table, so the row, column-header and cell roles are implied by tr, th and td and are deliberately not written — the APG’s own note, and the duplication a pattern check exists to refuse.",
+        "Exactly one cell is in the tab sequence, and the arrows move it. Focus is only put back into the DOM after a key moved it, never on a render, so a calendar on a page does not steal the reader’s place.",
+        "The heading is a polite live region, because paging with a key changes nothing that focus lands on and nothing else would announce the new month.",
+        "A column header shows the locale’s narrow weekday and carries the full name in abbr, which is the difference between a screen reader saying \"Mo\" and saying \"Monday\".",
+        "A date the predicate refuses carries aria-disabled rather than being removed, so a reader can arrow onto it and be told why it is out; and it is struck through as well as dimmed, because colour alone says nothing under forced colours.",
+        "Today is a dot under the number and focus is a ring around it. They were the same ring once, and a reader arrowing onto today saw one box and could not tell which of the two facts it was."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-calendar-active-background",
+    "--slotted-calendar-background",
+    "--slotted-calendar-cell-size",
+    "--slotted-calendar-color",
+    "--slotted-calendar-day-radius",
+    "--slotted-calendar-disabled-color",
+    "--slotted-calendar-hover-background",
+    "--slotted-calendar-in-range-color",
+    "--slotted-calendar-invalid-edge-width",
+    "--slotted-calendar-invalid-focus-ring-color",
+    "--slotted-calendar-outside-color",
+    "--slotted-calendar-preview-background",
+    "--slotted-calendar-preview-border-color",
+    "--slotted-calendar-radius",
+    "--slotted-calendar-range-active-background",
+    "--slotted-calendar-range-background",
+    "--slotted-calendar-range-border-color",
+    "--slotted-calendar-range-hover-background",
+    "--slotted-calendar-selected-background",
+    "--slotted-calendar-selected-color",
+    "--slotted-calendar-today-color",
+    "--slotted-calendar-trigger-color",
+    "--slotted-calendar-unavailable-color",
+    "--slotted-calendar-week-number-border-color",
+    "--slotted-calendar-week-number-color",
+    "--slotted-calendar-weekday-color",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-md",
+    "--slotted-control-gap-md",
+    "--slotted-control-height-md",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-foreground",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-font-weight-semibold",
+    "--slotted-highlight-tint-opacity",
+    "--slotted-radius-full",
+    "--slotted-radius-sm",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-4",
+    "--slotted-space-6",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One calendar with every axis on it, driven by the controls below the canvas. Arrow around it, page with PageUp and PageDown, and press the heading to walk up a view.",
+      "language": "html",
+      "source": "<div slCalendar locale=\"pt-BR\" (valueChange)=\"onValue($event)\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "selection",
+      "title": "One date",
+      "note": "The default mode. Pressing the chosen date again takes it back, which is the only way to empty the value without a control of its own.",
+      "language": "html",
+      "source": "<div slCalendar selectionMode=\"single\" [value]=\"value\" (valueChange)=\"onValue($event)\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "range",
+      "title": "A run of days",
+      "note": "Two presses make a range, and either end may come first: choosing the 11th and then the 7th means the 7th to the 11th. A third press starts again, because a range that only grew could never be narrowed.",
+      "language": "html",
+      "source": "<div slCalendar selectionMode=\"range\" [value]=\"run\"></div>\n<div slCalendar selectionMode=\"multiple\" [value]=\"dates\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "views",
+      "title": "Day, month and year",
+      "note": "Press the heading to walk up and Escape to walk down. A reader entering a birth date must not press \"previous month\" four hundred times, which is what these two views exist to prevent.",
+      "language": "html",
+      "source": "<div slCalendar defaultView=\"year\" (viewChange)=\"onView($event)\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "months",
+      "title": "More than one month",
+      "note": "Two or three months side by side, each with its own caption because the heading then names the span. Narrow the stage: a month that no longer fits wraps under the first rather than being withdrawn.",
+      "language": "html",
+      "source": "<div slCalendar selectionMode=\"range\" [months]=\"2\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "locale",
+      "title": "The locale writes the month",
+      "note": "The month name, the weekday names and the day a week starts on all come from Intl. A German week starts on Monday and a Brazilian one on Sunday, from the same component and no table.",
+      "language": "html",
+      "source": "<div slCalendar locale=\"pt-BR\"></div>\n<div slCalendar locale=\"de-DE\"></div>\n<div slCalendar locale=\"ja-JP\"></div>\n<div slCalendar locale=\"pt-BR\" [firstDayOfWeek]=\"1\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "range-bounds",
+      "title": "Bounds",
+      "note": "min and max fence what the reader may reach: an arrow that would leave the range stops at the edge, and a date outside it cannot be pressed at all.",
+      "language": "html",
+      "source": "<div slCalendar [min]=\"first\" [max]=\"last\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "unavailable",
+      "title": "Days that are refused",
+      "note": "A refused date stays focusable — aria-disabled, never disabled — so a reader can arrow onto it, be told why it is out, and arrow past. Struck through rather than only faded, because colour alone says nothing under forced colours.",
+      "language": "html",
+      "source": "<div slCalendar [isDateUnavailable]=\"isWeekend\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "week-numbers",
+      "title": "Week numbers",
+      "note": "ISO 8601 numbering, as a row header separated by a rule. The rule is what keeps the column from reading as an eighth day of the week.",
+      "language": "html",
+      "source": "<div slCalendar weekNumbers fixedWeeks [firstDayOfWeek]=\"1\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Read-only keeps the value legible and answers nothing; disabled takes every cell out of the tab sequence and paints today in the disabled ink; invalid retargets the focus ring rather than removing it.",
+      "language": "html",
+      "source": "<div slCalendar readOnly></div>\n<div slCalendar invalid></div>\n<div slCalendar disabled></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "density",
+      "title": "Density and width",
+      "note": "Seven columns of two-digit numbers make this the densest grid the library draws. Switch the toolbar to dense and narrow the stage: the cell is the room there is divided by the columns there are, bounded by the WCAG minimum below.",
+      "language": "html",
+      "source": "<div slCalendar fixedWeeks></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "A provider sets the shape once, provideSlotted the language; focusedDate is a value of its own a consumer may own; and the ref hands back focus() and focusDate(), which page the grid to reach a date.",
+      "language": "html",
+      "source": "<div slCalendar #cal=\"slCalendar\" locale=\"pt-BR\" (focusedDateChange)=\"onFocused($event)\"></div>\n<button type=\"button\" (click)=\"cal.focusDate(christmas)\">Ir para o Natal</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Every key the APG grid pattern lists, including the two a month grid needs that a list does not: PageUp and PageDown move a month, and Shift with either moves a year.",
+      "language": "html",
+      "source": "<!-- ArrowLeft / ArrowRight  a day, mirrored under dir=\"rtl\" -->\n<!-- ArrowUp / ArrowDown     the same weekday, a week either way -->\n<!-- Home / End              the first and last day of the displayed week -->\n<!-- PageUp / PageDown       a month, clamped to the last day it has -->\n<!-- Shift + PageUp / Down   a year, on the same terms -->\n<!-- Enter / Space           chooses the date focus is on -->\n<!-- Escape                  walks down a view, and out of nothing -->\n<div slCalendar></div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}