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

package/docs/color-picker.json

@@ -0,0 +1,523 @@
+{
+  "family": "color-picker",
+  "ui": "color-picker",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Color panel and color field in four notations."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle"
+    ],
+    "format": [
+      "hex",
+      "rgb",
+      "hsl",
+      "oklch"
+    ],
+    "alpha": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "colorPicker": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "format": "hex",
+        "alpha": true
+      },
+      "capabilities": [
+        "value",
+        "format",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "readOnly",
+        "invalid",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "selected"
+      ],
+      "parts": [
+        "root",
+        "area",
+        "area-thumb",
+        "channel",
+        "channel-thumb",
+        "row",
+        "swatch",
+        "previous",
+        "input",
+        "format",
+        "eyedropper",
+        "presets",
+        "preset",
+        "contrast",
+        "contrast-sample",
+        "contrast-ratio",
+        "contrast-level",
+        "gamut"
+      ]
+    },
+    "colorField": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "format": "hex",
+        "alpha": true
+      },
+      "capabilities": [
+        "value",
+        "format",
+        "open",
+        "appearance",
+        "size",
+        "disabled",
+        "readOnly",
+        "invalid",
+        "required",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "input",
+        "trigger",
+        "content"
+      ]
+    }
+  },
+  "docs": {
+    "colorPicker": {
+      "imports": {
+        "source": "import {\n  provideColorPickerDefaults,\n  SlColorField,\n  SlColorPicker,\n} from '@slotted/angular/color-picker';",
+        "selector": "div[slColorPicker], div[slColorField]",
+        "exportAs": "slColorPicker, slColorField"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div[slColorPicker]",
+          "required": true,
+          "purpose": "The panel. Carries data-ui=\"color-picker\", data-size, data-format, data-disabled, data-readonly, data-invalid and data-out-of-gamut, and every colour it paints as a runtime property: --slotted-color-picker-color, -opaque, -hue, -x, -y, -alpha, -previous, -contrast-with."
+        },
+        {
+          "part": "area",
+          "element": "div, drawn by the panel",
+          "required": false,
+          "purpose": "Saturation along the reading direction, brightness upward, over the pure hue. A press moves the thumb there and the pointer is captured until it lets go."
+        },
+        {
+          "part": "area-thumb",
+          "element": "div role=\"slider\"",
+          "required": false,
+          "purpose": "The one focusable point of the area: arrows move saturation and brightness by 1 %, Shift or PageUp/PageDown by 10 %. Its value text says both in words."
+        },
+        {
+          "part": "channel",
+          "element": "div, drawn by the panel",
+          "required": false,
+          "purpose": "The hue around the circle, drawn by one gradient interpolated the long way; or the alpha from nothing to whole over the transparency grid."
+        },
+        {
+          "part": "channel-thumb",
+          "element": "div role=\"slider\"",
+          "required": false,
+          "purpose": "The APG slider: arrows ±1, Shift and PageUp/PageDown ±10, Home and End to the ends. It travels inside its track, so at either end it still sits on the colour it names."
+        },
+        {
+          "part": "row",
+          "element": "div, drawn by the panel",
+          "required": false,
+          "purpose": "The preview, the value as text, its notation and the eyedropper, on one line."
+        },
+        {
+          "part": "swatch",
+          "element": "span role=\"img\"",
+          "required": false,
+          "purpose": "The colour now, over the transparency grid, named by its value."
+        },
+        {
+          "part": "previous",
+          "element": "button",
+          "required": false,
+          "purpose": "The colour the panel opened with, beside the colour now; pressing it restores that colour with the reason \"select\"."
+        },
+        {
+          "part": "input",
+          "element": "input, in a text-field frame",
+          "required": false,
+          "purpose": "The value as text in any notation. A colour still being written is aria-invalid and left alone; Enter or leaving commits it in the current notation, or puts back the last valid one. Always left-to-right."
+        },
+        {
+          "part": "format",
+          "element": "button with slMenuTriggerFor",
+          "required": false,
+          "purpose": "The notation — hex, rgb, hsl, oklch — as a menu of radio items; a change rewrites the value."
+        },
+        {
+          "part": "eyedropper",
+          "element": "button",
+          "required": false,
+          "purpose": "The platform’s EyeDropper, drawn only where window.EyeDropper exists; the colour picked arrives with the reason \"programmatic\"."
+        },
+        {
+          "part": "presets",
+          "element": "div role=\"radiogroup\"",
+          "required": false,
+          "purpose": "Colours offered as one press; arrow keys move and choose, the radio group’s own way."
+        },
+        {
+          "part": "preset",
+          "element": "button role=\"radio\"",
+          "required": false,
+          "purpose": "One preset, named by its value; the chosen one is ringed at a gap of the panel’s ground."
+        },
+        {
+          "part": "contrast",
+          "element": "div aria-live=\"polite\"",
+          "required": false,
+          "purpose": "Drawn when contrastWith is given: Aa in the colour over that background, the WCAG ratio, and the level in words — AAA, AA, AA large or Fail."
+        },
+        {
+          "part": "contrast-sample",
+          "element": "span",
+          "required": false,
+          "purpose": "The Aa sample."
+        },
+        {
+          "part": "contrast-ratio",
+          "element": "span",
+          "required": false,
+          "purpose": "The ratio, 5.17:1."
+        },
+        {
+          "part": "contrast-level",
+          "element": "span",
+          "required": false,
+          "purpose": "The level, a word in a toned badge."
+        },
+        {
+          "part": "gamut",
+          "element": "p role=\"status\"",
+          "required": false,
+          "purpose": "Drawn when an oklch value lies outside sRGB: the value is kept as written and the panel says the screen shows the nearest colour."
+        }
+      ],
+      "api": [
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle'",
+          "defaultValue": "outline",
+          "appliesTo": "slColorField",
+          "description": "The text-field frame of the field"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "from the field",
+          "appliesTo": "slColorField",
+          "description": "aria-required on the text, never the native attribute"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "Present means controlled: a colour in hex, rgb, hsl or oklch"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "#000000",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "What an uncontrolled picker starts from"
+        },
+        {
+          "name": "format",
+          "type": "'hex' | 'rgb' | 'hsl' | 'oklch'",
+          "defaultValue": "hex",
+          "appliesTo": "slColorPicker, slColorField, provideColorPickerDefaults",
+          "description": "The notation the value is written in; defaults to the value’s own, then to the provider’s. defaultFormat is the uncontrolled half"
+        },
+        {
+          "name": "alpha",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "Whether the colour carries an alpha channel"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slColorPicker, slColorField, provideColorPickerDefaults",
+          "description": "The step, read from the field first"
+        },
+        {
+          "name": "presets",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "slColorPicker, slColorField, provideColorPickerDefaults",
+          "description": "Colours offered as one press"
+        },
+        {
+          "name": "contrastWith",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "The background the contrast is measured against; absent, no contrast is drawn"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "Out of the tab order; the colour greyed"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "Focusable and legible; nothing moves"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "data-invalid on the root; aria-invalid on the text"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slColorField",
+          "description": "Present means the consumer owns whether the panel is open; defaultOpen is the uncontrolled half"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<ColorPickerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slColorPicker, slColorField",
+          "description": "Words laid over the language in force, key by key: what each control is called, the gamut sentence and the contrast levels"
+        }
+      ],
+      "composition": [
+        {
+          "name": "div[slColorField]",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "a form",
+          "description": "A text-field whose start is the swatch (data-part=\"trigger\"), opening the panel in a popover; its aria-label moves onto the text. [(open)] is a model"
+        },
+        {
+          "name": "provideColorPickerDefaults",
+          "type": "(defaults: Partial<ColorPickerDefaults>) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The notation, the palette and the size an application takes once"
+        },
+        {
+          "name": "exportAs",
+          "type": "slColorPicker, slColorField",
+          "defaultValue": "—",
+          "appliesTo": "templates",
+          "description": "Reach the instance; current() is the value in its notation"
+        }
+      ],
+      "events": [
+        {
+          "name": "(valueChange)",
+          "payload": "ChangeRequest<string>",
+          "when": "Before the colour moves, in the current notation: reason \"pointer\", \"keyboard\", \"select\" (a preset, the restore, a notation change) or \"programmatic\" (the eyedropper). cancel() refuses the move."
+        },
+        {
+          "name": "(formatChange)",
+          "payload": "ChangeRequest<ColorFormat>",
+          "when": "Before the notation changes, with reason \"select\"."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "payload": "the form’s own value",
+          "when": "On both slColorPicker and slColorField, whenever the colour moves and nobody refused it."
+        }
+      ],
+      "accessibility": [
+        "Each thumb is a slider with a name and a value text in words — \"Hue, 221°\", \"Opacity, 60 %\", \"Saturation and brightness, 84 %, 92 %\" — so the colour is never told by colour alone; the area thumb carries aria-roledescription \"2D slider\", the React Aria convention for a slider with two axes.",
+        "The keyboard is the APG slider for each channel and the APG radio group for the presets; in a right-to-left document the horizontal arrows follow the mirrored axis.",
+        "The contrast part names the level in words beside the ratio, and it is aria-live polite, so a reader adjusting the colour hears when it crosses AA.",
+        "The text is always left-to-right: a colour notation reads the same in every language.",
+        "Forced colours keep the reader’s colours visible: the area, the channels, the swatches and the presets opt out of the system palette, because a colour picker whose colours are replaced shows nothing."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-medium",
+    "--slotted-border-width-thin",
+    "--slotted-color-picker-channel-size",
+    "--slotted-color-picker-thumb-size",
+    "--slotted-color-picker-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-height-md",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-inner-size",
+    "--slotted-control-inner-size-lg",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-size-sm",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-radius-full",
+    "--slotted-radius-md",
+    "--slotted-radius-sm",
+    "--slotted-shadow-sm",
+    "--slotted-space-1",
+    "--slotted-space-12",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-surface",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-success-surface",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-surface",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The whole panel. Drag in the area, move the hue and the opacity, type a colour in any notation, change the notation, pick a preset; the value under the panel is what onValueChange receives.",
+      "language": "html",
+      "source": "<div slColorPicker defaultValue=\"#2563EB\" (valueChange)=\"color.set($event.value)\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "field",
+      "title": "A field that holds a colour",
+      "note": "The swatch in the field’s start opens the panel in a popover; the text takes any notation and keeps the one shown. In a Field, the label names the text.",
+      "language": "html",
+      "source": "<div slField>\n  <label slFieldLabel>Cor primária</label>\n  <div slColorField [formControl]=\"primary\" [presets]=\"brand\"></div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "panel",
+      "title": "Choosing the parts",
+      "note": "The parts are chosen by inputs: alpha off and no presets leave the area, the hue and the row, for a settings row with no room for more.",
+      "language": "html",
+      "source": "<div slColorPicker [alpha]=\"false\" [presets]=\"[]\" defaultValue=\"#16A34A\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "formats",
+      "title": "Four notations, one colour",
+      "note": "The value comes back in the notation shown. Change it in the menu and the value is rewritten; type another notation and it is converted to this one.",
+      "language": "html",
+      "source": "<div\n  slColorPicker\n  defaultValue=\"#2563EB\"\n  [format]=\"format()\"\n  (formatChange)=\"format.set($event.value)\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "alpha",
+      "title": "Opacity",
+      "note": "The alpha channel fades the colour over the transparency grid, drawn from the theme’s own surfaces. alpha={false} removes it for a colour that must be opaque — a brand colour, a text colour.",
+      "language": "html",
+      "source": "<div slColorPicker defaultValue=\"rgb(22 163 74 / 60%)\"></div>\n<div slColorPicker defaultValue=\"#16A34A\" [alpha]=\"false\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "presets",
+      "title": "A palette as one press",
+      "note": "The presets are a radio group: arrow keys move and choose. The chosen one is ringed; a value that matches none leaves the first focusable.",
+      "language": "ts",
+      "source": "providers: [provideColorPickerDefaults({ presets: ['#0F172A', '#DC2626', '#16A34A', '#2563EB'] })];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "contrast",
+      "title": "Contrast against the background it will sit on",
+      "note": "contrastWith names the background; the panel shows Aa in the colour over it, the WCAG ratio and the level in words. An alpha colour is composited first, because that is what the reader sees.",
+      "language": "html",
+      "source": "<div slColorPicker defaultValue=\"#64748B\" contrastWith=\"#FFFFFF\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Disabled, read-only and out of gamut",
+      "note": "Disabled greys the colour and takes the panel out of the tab order; read-only keeps the sliders focusable and moves nothing; an oklch colour outside sRGB is said, never quietly clipped.",
+      "language": "html",
+      "source": "<div slColorPicker disabled defaultValue=\"#64748B\"></div>\n<div slColorPicker readOnly defaultValue=\"#DB2777\"></div>\n<div slColorPicker defaultValue=\"oklch(0.9 0.3 150)\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once",
+      "note": "The provider carries the notation and the palette; the words come from the language in force.",
+      "language": "html",
+      "source": "<div slColorPicker #picker=\"slColorPicker\" [formControl]=\"color\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does",
+      "note": "Tab reaches the area, each channel, the restore, the text, the notation, the eyedropper and the chosen preset. Arrows move by 1, Shift and PageUp/PageDown by 10, Home and End to the ends of a channel; in a right-to-left document the horizontal arrows follow the mirrored axis.",
+      "language": "html",
+      "source": "<div slColorPicker defaultValue=\"#2563EB\"></div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}