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

package/docs/date-field.json

@@ -0,0 +1,490 @@
+{
+  "family": "date-field",
+  "ui": "date-field",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Typed date input split into segments."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "calendar": [
+      "gregory"
+    ]
+  },
+  "members": {
+    "dateField": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "calendar": "gregory",
+        "clearable": false,
+        "yearPivot": 20
+      },
+      "capabilities": [
+        "value",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly",
+        "required"
+      ],
+      "parts": [
+        "root",
+        "segments",
+        "segment",
+        "literal",
+        "start",
+        "end",
+        "clear",
+        "hidden-input"
+      ]
+    }
+  },
+  "docs": {
+    "dateField": {
+      "imports": {
+        "source": "import { SlDateField, SlDateFieldStart, SlDateFieldEnd } from '@slotted/angular/date-field';",
+        "selector": "[slDateField]",
+        "exportAs": "slDateField"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, the consumer’s own element",
+          "required": true,
+          "purpose": "The frame. Carries data-ui=\"date-field\", the axes, and data-disabled, data-invalid, data-readonly and data-required. It has no role of its own: the group inside is what a screen reader meets. The consumer writes this element, so its classes, its attributes and its own directives are its own."
+        },
+        {
+          "part": "segments",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"group\", whose accessible name is the whole date in words. The APG’s spin-button example names the group as the thing that tells a screen-reader user that three buttons are one date, so a reader hears \"9 de setembro de 2026\" without visiting all three and remembering each."
+        },
+        {
+          "part": "segment",
+          "element": "div",
+          "required": true,
+          "purpose": "One field of the date, as role=\"spinbutton\" with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext. There is one per field the locale writes, in the locale’s own order, and exactly one of them is in the tab sequence. data-field says which field it holds and data-placeholder says it holds nothing yet."
+        },
+        {
+          "part": "literal",
+          "element": "span",
+          "required": true,
+          "purpose": "The separator the locale writes between two fields — a slash, a full stop, a hyphen. It is aria-hidden: the group already carries the date in words, and a screen reader reading \"slash\" between two numbers is reading punctuation aloud."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "An adornment before the date in the reading direction: a calendar mark, a label, an icon. It is its own bidi run, and any icon inside it is sized from the control’s own glyph scale."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "An adornment after the date in the reading direction: a time zone, a note, a unit."
+        },
+        {
+          "part": "clear",
+          "element": "button",
+          "required": false,
+          "purpose": "Empties every segment with reason \"clear\" and returns focus to the first one. Drawn only when there is something to clear and the reader may change it, and never smaller than 24 CSS pixels."
+        },
+        {
+          "part": "hidden-input",
+          "element": "input",
+          "required": true,
+          "purpose": "type=\"hidden\", carrying the value as an ISO 8601 YYYY-MM-DD string under the name input. It is what makes the control work in a plain form post without JavaScript reading it — the decision currency-field already took for a number."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "PlainDate | null",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "The date the control shows. Present means the consumer owns it: the control asks and waits rather than moving it."
+        },
+        {
+          "name": "defaultValue",
+          "type": "PlainDate | null",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "The date the control starts from when nobody else writes one. Read once, in ngOnInit, because Angular binds inputs after it constructs a component."
+        },
+        {
+          "name": "min",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "The earliest date the control accepts. Reported through each segment’s aria-valuemin, and as the slottedDateRange form error."
+        },
+        {
+          "name": "max",
+          "type": "PlainDate",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "The latest date the control accepts, on the same terms as min."
+        },
+        {
+          "name": "isDateUnavailable",
+          "type": "(date: PlainDate) => boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Refuses particular dates — a weekend, a holiday, a day already booked. Reported as the slottedDateUnavailable form error."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the language in force",
+          "appliesTo": "SlDateField",
+          "description": "BCP 47. Decides the field order, the separators, the placeholder and the language a month is announced in."
+        },
+        {
+          "name": "timeZone",
+          "type": "string",
+          "defaultValue": "the runtime’s",
+          "appliesTo": "SlDateField",
+          "description": "Which zone answers \"what is today\", and nothing else. The value itself has no zone."
+        },
+        {
+          "name": "firstDayOfWeek",
+          "type": "number",
+          "defaultValue": "the locale’s",
+          "appliesTo": "SlDateField",
+          "description": "0 is Sunday. Unused by the field itself; it is here so one provider configures the field and the calendar beside it."
+        },
+        {
+          "name": "yearPivot",
+          "type": "number",
+          "defaultValue": "20",
+          "appliesTo": "SlDateField",
+          "description": "How far ahead a two-digit year may land before it is read as last century. 0 sends every future year into the past, which is what a birth date wants."
+        },
+        {
+          "name": "calendar",
+          "type": "'gregory'",
+          "defaultValue": "gregory",
+          "appliesTo": "SlDateField",
+          "description": "The calendar system the value is written in. One value today, and an axis rather than a silence so a second one is not a contract break."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "SlDateField",
+          "description": "The type step, matching the field around it."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "SlDateField",
+          "description": "How much frame the control shows at rest."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Unstated rather than false, so the control defers to the field. A form that disables the control from its model reaches the same state."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Readable, copyable and focusable, and not changeable. Arrow keys still walk between fields; nothing steps."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Unstated rather than false. Retargets the focus ring."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Unstated rather than false. Reaches the group as aria-required."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlDateField",
+          "description": "Draws a button that empties the value and returns focus to the first segment."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<DateFieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Words laid over the language in force, key by key: the clear button’s accessible name (clear)."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "The name the hidden input carries the ISO string under, for a plain form post."
+        }
+      ],
+      "composition": [
+        {
+          "name": "provideDateFieldDefaults",
+          "type": "Provider",
+          "defaultValue": "—",
+          "appliesTo": "application",
+          "description": "Sets timeZone, firstDayOfWeek, yearPivot, calendar, size and variant once for everything under the injector. A control that states any of them itself still wins."
+        },
+        {
+          "name": "exportAs",
+          "type": "slDateField",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "Hands a template the instance, so focus(), clear() and the derived date() signal are reachable without a component of its own."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "type": "implemented",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "formControl, formControlName and ngModel all drive the control, and a form that disables it from its model reaches setDisabledState."
+        },
+        {
+          "name": "Validator",
+          "type": "implemented",
+          "defaultValue": "—",
+          "appliesTo": "SlDateField",
+          "description": "min, max and isDateUnavailable report as slottedDateRange and slottedDateUnavailable. required is left to Angular’s own validator, because a form already has a word for it and two would disagree."
+        },
+        {
+          "name": "slDateFieldStart / slDateFieldEnd",
+          "type": "Directive",
+          "defaultValue": "—",
+          "appliesTo": "consumer element",
+          "description": "The two adornment slots, as directives on the consumer’s own element, so an icon, a kbd or a span all keep their own semantics."
+        }
+      ],
+      "events": [
+        {
+          "name": "valueChange",
+          "payload": "DateFieldChangeRequest",
+          "when": "Before the value moves, and cancellable. The request carries the new value, the value it replaces, the segments, the reason and the originating event. It arrives when a run of typed digits ends — on the digit that fills a field, on the key that leaves it, or on blur — never on every keystroke inside one, because typing 2026 into a year passes through 2, 20 and 202 on the way. There is no two-way [(value)]: one slot could carry none of that."
+        }
+      ],
+      "accessibility": [
+        "The three fields are a role=\"group\" whose accessible name is the whole date in words, which is what the APG’s spin-button example names as the thing that lets a screen-reader user perceive a date without visiting all three buttons and remembering each.",
+        "Each field is a role=\"spinbutton\" carrying aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext — and the month’s valuetext is its name, because \"nine\" is not September in any language a reader is thinking in.",
+        "Exactly one field is in the tab sequence at a time; the arrows walk between them and mirror in a right-to-left document, because the keys are physical and the order they walk is the writing order.",
+        "The APG’s own example is marked deprecated for its visible arrow buttons, which duplicate keys the reader already has. This family draws none, and takes the roles, the wrapping rules and the aria-valuetext guidance whole.",
+        "A step wraps inside its own field and never carries: December steps up to January without moving the year, which is the example’s stated rule and the difference between one arrow press changing one field and changing two."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-date-field-action-active-background",
+    "--slotted-date-field-action-color",
+    "--slotted-date-field-action-hover-background",
+    "--slotted-date-field-action-size",
+    "--slotted-date-field-adornment-color",
+    "--slotted-date-field-background",
+    "--slotted-date-field-border-color",
+    "--slotted-date-field-color",
+    "--slotted-date-field-disabled-background",
+    "--slotted-date-field-disabled-border-color",
+    "--slotted-date-field-disabled-color",
+    "--slotted-date-field-hover-border-color",
+    "--slotted-date-field-icon-size-min",
+    "--slotted-date-field-invalid-border-color",
+    "--slotted-date-field-invalid-edge-width",
+    "--slotted-date-field-invalid-focus-ring-color",
+    "--slotted-date-field-literal-color",
+    "--slotted-date-field-placeholder-color",
+    "--slotted-date-field-plain-hover-background",
+    "--slotted-date-field-radius",
+    "--slotted-date-field-readonly-background",
+    "--slotted-date-field-segment-focus-background",
+    "--slotted-date-field-segment-focus-color",
+    "--slotted-date-field-segment-min-inline-size",
+    "--slotted-date-field-segment-padding-inline",
+    "--slotted-date-field-segment-radius",
+    "--slotted-date-field-shadow",
+    "--slotted-date-field-subtle-background",
+    "--slotted-date-field-subtle-border-color",
+    "--slotted-date-field-subtle-hover-background",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-radius-none",
+    "--slotted-radius-xs",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One control with every input on it, driven by the controls below the canvas. Type into it: each field takes digits, the arrows step it, and the clear button appears only once there is something to clear.",
+      "language": "html",
+      "source": "<div slField>\n  <label slFieldLabel>Vencimento</label>\n  <div slDateField clearable locale=\"pt-BR\" name=\"vencimento\"></div>\n  <span slFieldDescription>A fatura vence nesta data.</span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "locale",
+      "title": "The locale writes the date",
+      "note": "The same directive in four locales. The field order, the separators and the placeholder all come from Intl — nobody writes a format string, and a Japanese reader gets the year first.",
+      "language": "html",
+      "source": "<div slDateField locale=\"pt-BR\"></div>\n<div slDateField locale=\"en-US\"></div>\n<div slDateField locale=\"de-DE\"></div>\n<div slDateField locale=\"ja-JP\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Size",
+      "note": "The three steps a field can be. A control inside a field takes the field’s step, so a form cannot end up with a small field holding a medium control on one row.",
+      "language": "html",
+      "source": "<div slDateField size=\"sm\"></div>\n<div slDateField size=\"md\"></div>\n<div slDateField size=\"lg\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "Variant",
+      "note": "How much frame the control shows. outline takes the ground it is on, subtle sinks into the page, and plain shows nothing until it is used — which is what a dense table needs.",
+      "language": "html",
+      "source": "<div slDateField variant=\"outline\"></div>\n<div slDateField variant=\"subtle\"></div>\n<div slDateField variant=\"plain\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "range",
+      "title": "Bounds and unavailable dates",
+      "note": "min and max fence the value, and isDateUnavailable refuses particular days. Both are also form validity rules, so a reactive form reports them without a validator of its own.",
+      "language": "html",
+      "source": "<div\n  slDateField\n  [min]=\"{ year: 2026, month: 1, day: 1 }\"\n  [max]=\"{ year: 2026, month: 12, day: 31 }\"\n  [isDateUnavailable]=\"isHoliday\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Read-only stays focusable and copyable and never looks disabled; disabled answers no key and no pointer; invalid keeps its focus ring and retargets its colour. Tab through the row to see each one answer.",
+      "language": "html",
+      "source": "<div slDateField readOnly></div>\n<div slDateField invalid></div>\n<div slDateField disabled></div>\n<div slDateField required></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "clear",
+      "title": "Clearing",
+      "note": "The button appears only once a segment holds something, and pressing it empties every field, emits the clear reason and puts focus back on the first segment rather than leaving it nowhere.",
+      "language": "html",
+      "source": "<div slDateField clearable [messages]=\"{ clear: 'Limpar a data' }\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "adornments",
+      "title": "Adornments",
+      "note": "The two slots are directives on the consumer’s own element, so an icon, a kbd or a span all work and none of them loses its own semantics.",
+      "language": "html",
+      "source": "<div slDateField>\n  <sl-icon slDateFieldStart name=\"calendar\" />\n  <span slDateFieldEnd>UTC-3</span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "forms",
+      "title": "In a form",
+      "note": "Reactive Forms drives it through ControlValueAccessor, and min, max and isDateUnavailable report as form errors through Validator — the two integration points React has no equivalent of.",
+      "language": "html",
+      "source": "<form [formGroup]=\"form\">\n  <div slField>\n    <label slFieldLabel>Vencimento</label>\n    <div slDateField formControlName=\"vencimento\" [min]=\"today\"></div>\n    <span slFieldError>Escolha uma data futura.</span>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "A date halfway through",
+      "note": "A day and a month with no year is not a date, so the value is null and the hidden input is empty — and that is not the same as an empty field. The request carries the segments, which is what a draft is saved from.",
+      "language": "html",
+      "source": "<div slDateField (valueChange)=\"onRequest($event)\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "provideDateFieldDefaults sets the zone and the pivot once, provideSlotted the language; exportAs hands a template the instance; and focus() and clear() are the two actions no input can express.",
+      "language": "html",
+      "source": "<div slDateField #data=\"slDateField\" locale=\"pt-BR\"></div>\n<button type=\"button\" (click)=\"data.clear()\">Limpar</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Every key the spin-button pattern lists, on the field that has focus. Note two behaviours nothing else here has: a step wraps inside its own field, and a day a short month could not hold comes back when a longer one can.",
+      "language": "html",
+      "source": "<!-- ArrowUp / ArrowDown  step one, wrapping inside the field -->\n<!-- PageUp / PageDown    five for a day or a month, ten for a year -->\n<!-- Home / End           the field's lowest and highest value -->\n<!-- ArrowLeft / Right    the previous and next field, in writing order -->\n<!-- 0-9                  fills the field and moves on when it is full -->\n<!-- Backspace / Delete   empties one field back to its placeholder -->\n<div slDateField></div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}