@vielzeug/codex 26.10.15 → 26.10.17

package/data/refine.json

@@ -1766,6 +1766,13 @@
         },
         "description": "Internal padding: 'none' | 'sm' | 'md' | 'lg' | 'xl'"
       },
+      {
+        "name": "rounded",
+        "type": {
+          "text": "'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'"
+        },
+        "description": "Border radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'"
+      },
       {
         "name": "elevation",
         "type": {
@@ -3493,7 +3500,7 @@
     "cssProperties": [
       {
         "name": "--rank-number-color",
-        "description": "Rank numeral color (default --color-contrast-500)"
+        "description": "Rank numeral color (default --color-contrast-600)"
       },
       {
         "name": "--rank-number-width",
@@ -3505,7 +3512,7 @@
       },
       {
         "name": "--rank-track-color",
-        "description": "Bar track color (default --color-contrast-100)"
+        "description": "Bar track color (default --color-contrast-200)"
       },
       {
         "name": "--rank-bar-height",
@@ -3644,10 +3651,10 @@
     "kind": "variable",
     "name": "SPEECH_RATES",
     "type": {
-      "text": "[1, 0.85, 1.15, 1.5]"
+      "text": "[1, 1.15, 1.5, 0.85]"
     },
-    "default": "[1, 0.85, 1.15, 1.5]",
-    "description": "The playback multipliers the speed control cycles through."
+    "default": "[1, 1.15, 1.5, 0.85]",
+    "description": "The playback multipliers the speed control cycles through, in cycle order: the first\ntap from the default 1× speeds the reading up, and the slow step returns last."
   },
   {
     "kind": "function",
@@ -3667,6 +3674,37 @@
     ],
     "description": "The entry's sentences: prose ends . ! or ?, closing quotes belong to the sentence\nthey end, and an unterminated tail is still a sentence. Consumers that highlight what\nis being read build their display from this same list, so `progress` sentence indexes\nmap onto their own."
   },
+  {
+    "kind": "function",
+    "name": "pickVoice",
+    "return": {
+      "type": {
+        "text": "VoiceCandidate | null"
+      }
+    },
+    "parameters": [
+      {
+        "name": "voices",
+        "type": {
+          "text": "VoiceCandidate[]"
+        }
+      },
+      {
+        "name": "lang",
+        "type": {
+          "text": "string | null"
+        }
+      },
+      {
+        "name": "name",
+        "optional": true,
+        "type": {
+          "text": "string"
+        }
+      }
+    ],
+    "description": "The voice to read with: an exact (then substring, case-insensitive) name match wins;\notherwise the best-ranked voice for `lang`, or `null` to leave the choice to the\nengine's own `lang` hint."
+  },
   {
     "kind": "variable",
     "name": "SPEECH_PLAYER_TAG",
@@ -3674,14 +3712,14 @@
       "text": "'ore-speech-player'"
     },
     "default": "'ore-speech-player'",
-    "description": "A text-to-speech player control: reads its `text` aloud through the Web Speech API.\n\nRenders a labeled play/pause toggle (the label folds away once engaged), a stop\ncontrol beside it that appears while reading, and a speed control cycling\n1×/0.85×/1.15×/1.5×. The text is spoken sentence by sentence (long sentences split into pieces under the\nengine's truncation window), the `state` attribute reflects playback, a\n`role=\"status\"` live region announces transitions, and `progress` events name the\nsentence being read so a consumer can highlight it. Only one player speaks at a\ntime: starting one stops any other. `resume-at` names the sentence to begin from,\nso a persisted position makes resume mean it."
+    "description": "A text-to-speech player control: reads its `text` aloud through the Web Speech API.\n\nRenders an icon-only play/pause toggle, a speed control cycling\n1×/1.15×/1.5×/0.85×, a stop control that appears while reading, and a\nsentence-position readout. The text is spoken sentence by sentence (long sentences\nsplit into pieces under the\nengine's truncation window), the `state` attribute reflects playback, a\n`role=\"status\"` live region announces transitions, and `progress` events name the\nsentence being read so a consumer can highlight it. While reading, the Media Session\nAPI (where available) exposes play/pause/stop to the browser's own media controls.\nOnly one player speaks at a time: starting one stops any other. `resume-at` names the\nsentence to begin from, so a persisted position makes resume mean it."
   },
   {
     "kind": "class",
     "name": "OreSpeechPlayerElement",
     "tagName": "ore-speech-player",
     "customElement": true,
-    "description": "A text-to-speech player control: reads its `text` aloud through the Web Speech API.\nRenders a labeled play/pause toggle (the label folds away once engaged), a stop\ncontrol beside it that appears while reading, and a speed control cycling\n1×/0.85×/1.15×/1.5×. The text is spoken sentence by sentence (long sentences split into pieces under the\nengine's truncation window), the `state` attribute reflects playback, a\n`role=\"status\"` live region announces transitions, and `progress` events name the\nsentence being read so a consumer can highlight it. Only one player speaks at a\ntime: starting one stops any other. `resume-at` names the sentence to begin from,\nso a persisted position makes resume mean it.",
+    "description": "A text-to-speech player control: reads its `text` aloud through the Web Speech API.\nRenders an icon-only play/pause toggle, a speed control cycling\n1×/1.15×/1.5×/0.85×, a stop control that appears while reading, and a\nsentence-position readout. The text is spoken sentence by sentence (long sentences\nsplit into pieces under the\nengine's truncation window), the `state` attribute reflects playback, a\n`role=\"status\"` live region announces transitions, and `progress` events name the\nsentence being read so a consumer can highlight it. While reading, the Media Session\nAPI (where available) exposes play/pause/stop to the browser's own media controls.\nOnly one player speaks at a time: starting one stops any other. `resume-at` names the\nsentence to begin from, so a persisted position makes resume mean it.\n  voice for `lang` is picked automatically",
     "summary": "",
     "attributes": [
       {
@@ -3710,7 +3748,28 @@
         "type": {
           "text": "number"
         },
-        "description": "Playback rate; the speed control cycles 1 → 0.85 → 1.15 → 1.5"
+        "description": "Playback rate; the speed control cycles 1 → 1.15 → 1.5 → 0.85"
+      },
+      {
+        "name": "pitch",
+        "type": {
+          "text": "number"
+        },
+        "description": "Voice pitch passed to the engine, 0 to 2 (1 is natural)"
+      },
+      {
+        "name": "volume",
+        "type": {
+          "text": "number"
+        },
+        "description": "Voice loudness passed to the engine, 0 to 1"
+      },
+      {
+        "name": "voice",
+        "type": {
+          "text": "string"
+        },
+        "description": "Name of the voice to read with; unset, the most natural-sounding"
       },
       {
         "name": "resume-at",
@@ -3771,15 +3830,15 @@
       },
       {
         "name": "play",
-        "description": "The play/pause toggle button"
+        "description": "The play/pause toggle (an `ore-button`: style its `button` part through it)"
       },
       {
         "name": "rate",
-        "description": "The speed control"
+        "description": "The speed control (an `ore-button`)"
       },
       {
         "name": "stop",
-        "description": "The stop button (hidden while idle)"
+        "description": "The stop button (an `ore-button`, hidden while idle)"
       }
     ],
     "cssProperties": [
@@ -3789,16 +3848,12 @@
       },
       {
         "name": "--speech-player-control-size",
-        "description": "Each control's hit-area size (the toggle grows with its label)"
+        "description": "Each control's hit-area size"
       },
       {
         "name": "--speech-player-icon-color",
         "description": "Control icon color at rest"
       },
-      {
-        "name": "--speech-player-active-color",
-        "description": "Toggle color while reading (playing or paused)"
-      },
       {
         "name": "--speech-player-hover-bg",
         "description": "Control background on hover"
@@ -3878,6 +3933,13 @@
           "text": "string"
         },
         "description": "Read-only playback state: idle | playing | paused | ended"
+      },
+      {
+        "name": "fullscreen",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Read-only; present while the reader fills the screen"
       }
     ],
     "events": [
@@ -3946,7 +4008,11 @@
     "cssProperties": [
       {
         "name": "--speed-reading-font-size",
-        "description": "Display type size (default var(--text-2xl))"
+        "description": "Maximum display type size (default var(--text-3xl))"
+      },
+      {
+        "name": "--speed-reading-fullscreen-font-size",
+        "description": "Maximum fullscreen display type size (default min(10vw, var(--size-96)))"
       },
       {
         "name": "--speed-reading-min-font-size",
@@ -14234,6 +14300,75 @@
     ],
     "description": "Shared logic for floating-panel triggers (tooltip, popover).\n\nHandles:\n- Slot-based trigger element detection and rebinding\n- Event binding per trigger type (hover / focus / click)\n- Floating-element positioning via `@vielzeug/orbit`\n- Controlled mode via `openProp` watcher\n- Keyboard escape dismissal\n\nARIA binding is intentionally delegated to the caller via `bindTriggerAria`\nso that tooltip (`describedby`) and popover (`expanded`/`controls`/…) can diverge."
   },
+  {
+    "kind": "variable",
+    "name": "SPOTLIGHT_TAG",
+    "type": {
+      "text": "'ore-spotlight'"
+    },
+    "default": "'ore-spotlight'",
+    "description": "A dim layer with a hole punched in it, so one region of the page stays at full\nbrightness while everything else recedes.\n\nThe dim is a single oversized box-shadow on the cutout element, so the hole\nanimates with the element's own geometry: when a tour moves to the next step,\nthe highlight slides to the new target instead of blinking out and back.\n\nThe layer never captures pointer events: a beacon shows the way, it does not\nblock the road. The element inside the cutout stays clickable, and whatever\ndialog or popover owns the moment handles interaction and announcement: this\nlayer is decorative by definition and carries `aria-hidden`."
+  },
+  {
+    "kind": "class",
+    "name": "OreSpotlightElement",
+    "tagName": "ore-spotlight",
+    "customElement": true,
+    "description": "A dim layer with a hole punched in it, so one region of the page stays at full\nbrightness while everything else recedes.\nThe dim is a single oversized box-shadow on the cutout element, so the hole\nanimates with the element's own geometry: when a tour moves to the next step,\nthe highlight slides to the new target instead of blinking out and back.\nThe layer never captures pointer events: a beacon shows the way, it does not\nblock the road. The element inside the cutout stays clickable, and whatever\ndialog or popover owns the moment handles interaction and announcement: this\nlayer is decorative by definition and carries `aria-hidden`.",
+    "summary": "",
+    "attributes": [
+      {
+        "name": "radius",
+        "type": {
+          "text": "number"
+        },
+        "description": "Cutout corner radius in px (default: 8)",
+        "default": "8"
+      },
+      {
+        "name": "visible",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Show the dim layer (default: true)",
+        "default": "true"
+      }
+    ],
+    "cssParts": [
+      {
+        "name": "overlay",
+        "description": "The fixed dim layer."
+      },
+      {
+        "name": "cutout",
+        "description": "The highlighted rectangle."
+      }
+    ],
+    "cssProperties": [
+      {
+        "name": "--spotlight-dim",
+        "description": "Dim color (default: var(--color-scrim))"
+      },
+      {
+        "name": "--spotlight-ring",
+        "description": "Ring drawn around the cutout (default: none)"
+      },
+      {
+        "name": "--spotlight-radius",
+        "description": "Cutout corner radius"
+      },
+      {
+        "name": "--spotlight-transition",
+        "description": "Geometry transition (default: 240ms ease)"
+      }
+    ],
+    "demos": [
+      {
+        "url": "",
+        "description": "```html\n<ore-spotlight></ore-spotlight>\n<script type=\"module\">\n  import '@vielzeug/refine/spotlight';\n  const spotlight = document.querySelector('ore-spotlight');\n  spotlight.rect = document.querySelector('#cta').getBoundingClientRect();\n</script>\n```"
+      }
+    ]
+  },
   {
     "kind": "variable",
     "name": "TOOLTIP_TAG",
@@ -14354,5 +14489,274 @@
         "description": "```html\n<!-- Simple text tooltip -->\n<ore-tooltip content=\"Copy to clipboard\">\n  <button>Copy</button>\n</ore-tooltip>\n<!-- Placement and delay -->\n<ore-tooltip content=\"Save your work\" placement=\"right\" delay=\"300\">\n  <ore-icon name=\"save\"></ore-icon>\n</ore-tooltip>\n<!-- Hover + focus trigger -->\n<ore-tooltip content=\"Required field\" trigger=\"hover,focus\" placement=\"top\">\n  <ore-input label=\"Email\" type=\"email\"></ore-input>\n</ore-tooltip>\n<!-- Rich content slot -->\n<ore-tooltip>\n  <ore-button>Help</ore-button>\n  <div slot=\"content\">\n    <strong>Keyboard shortcuts</strong>\n    <p>Press Ctrl+S to save.</p>\n  </div>\n</ore-tooltip>\n```"
       }
     ]
+  },
+  {
+    "kind": "variable",
+    "name": "TOUR_PRESENTATIONS",
+    "type": {
+      "text": "['auto', 'bottom-sheet', 'modal', 'popover']"
+    },
+    "default": "['auto', 'bottom-sheet', 'modal', 'popover']"
+  },
+  {
+    "kind": "variable",
+    "name": "TOUR_TAG",
+    "type": {
+      "text": "'ore-tour'"
+    },
+    "default": "'ore-tour'",
+    "description": "The step card of a product tour: a compact dialog with title, body, progress,\nand Skip / Back / Next actions (Skip leads the row, away from Next).\n\nThe card is deliberately dumb: it owns no step logic and no persistence. It\nrenders the step the app hands it and emits `next` / `back` / `skip` /\n`finish` / `dismiss`; a `@vielzeug/beacon` tour handle (or any state the app\nalready keeps) decides what happens. `bind(handle)` wires both directions in\none call, or the app drives the `open`, `title`, `description`,\n`step-index`, and `anchor` props and listens to the events itself.\n\nPresentations: `popover` anchors the card to `anchor` with an Orbit\npositioner in the Popover API top layer; `modal` and `bottom-sheet` render a\nnative `<dialog>` (centered panel or bottom-anchored sheet) with the\nstandard focus trap and background lock; `auto` picks bottom-sheet on narrow\nviewports and popover otherwise.\n\nKeyboard: Escape requests dismissal (native in dialog presentations, keydown\nin popover mode); ArrowLeft / ArrowRight emit `back` / `next` while open."
+  },
+  {
+    "kind": "class",
+    "name": "OreTourElement",
+    "tagName": "ore-tour",
+    "customElement": true,
+    "description": "The step card of a product tour: a compact dialog with title, body, progress,\nand Skip / Back / Next actions (Skip leads the row, away from Next).\nThe card is deliberately dumb: it owns no step logic and no persistence. It\nrenders the step the app hands it and emits `next` / `back` / `skip` /\n`finish` / `dismiss`; a `@vielzeug/beacon` tour handle (or any state the app\nalready keeps) decides what happens. `bind(handle)` wires both directions in\none call, or the app drives the `open`, `title`, `description`,\n`step-index`, and `anchor` props and listens to the events itself.\nPresentations: `popover` anchors the card to `anchor` with an Orbit\npositioner in the Popover API top layer; `modal` and `bottom-sheet` render a\nnative `<dialog>` (centered panel or bottom-anchored sheet) with the\nstandard focus trap and background lock; `auto` picks bottom-sheet on narrow\nviewports and popover otherwise.\nKeyboard: Escape requests dismissal (native in dialog presentations, keydown\nin popover mode); ArrowLeft / ArrowRight emit `back` / `next` while open.\n  card and route the card's actions back into it. Returns an unsubscribe.",
+    "summary": "",
+    "attributes": [
+      {
+        "name": "anchor",
+        "type": {
+          "text": "object"
+        },
+        "description": "Anchor element, virtual reference, or viewport-space rect (popover mode)"
+      },
+      {
+        "name": "description",
+        "type": {
+          "text": "string"
+        },
+        "description": "Body text (replaced by the default slot)"
+      },
+      {
+        "name": "dismissible",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Show a close (×) button (default true)"
+      },
+      {
+        "name": "initial-focus",
+        "type": {
+          "text": "string"
+        },
+        "description": "Selector for the element to focus on open (dialog presentations)"
+      },
+      {
+        "name": "offset",
+        "type": {
+          "text": "number"
+        },
+        "description": "Anchor gap in px (popover mode, default 8)"
+      },
+      {
+        "name": "open",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Controlled open state"
+      },
+      {
+        "name": "persistent",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Escape/backdrop do not request dismissal"
+      },
+      {
+        "name": "placement",
+        "type": {
+          "text": "string"
+        },
+        "description": "Popover placement (default 'bottom')"
+      },
+      {
+        "name": "presentation",
+        "type": {
+          "text": "'bottom-sheet' | 'modal' | 'popover'"
+        },
+        "description": "'auto' (default) | 'bottom-sheet' | 'modal' | 'popover'"
+      },
+      {
+        "name": "return-focus",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Restore focus after the card closes (default true)"
+      },
+      {
+        "name": "spotlight",
+        "type": {
+          "text": "boolean"
+        },
+        "description": "Dim the page around the anchor with an ore-spotlight cutout"
+      },
+      {
+        "name": "step-index",
+        "type": {
+          "text": "number"
+        },
+        "description": "Zero-based current step (default 0)"
+      },
+      {
+        "name": "title",
+        "type": {
+          "text": "string"
+        },
+        "description": "Card title"
+      },
+      {
+        "name": "total-steps",
+        "type": {
+          "text": "number"
+        },
+        "description": "Total steps; >0 shows the progress bar and step counter"
+      }
+    ],
+    "events": [
+      {
+        "name": "back",
+        "description": "Back was requested.",
+        "type": {
+          "text": "CustomEvent"
+        }
+      },
+      {
+        "name": "dismiss",
+        "description": "Close was requested. detail: { reason }",
+        "type": {
+          "text": "CustomEvent"
+        }
+      },
+      {
+        "name": "finish",
+        "description": "Advance was pressed on the final step.",
+        "type": {
+          "text": "CustomEvent"
+        }
+      },
+      {
+        "name": "next",
+        "description": "Next was requested.",
+        "type": {
+          "text": "CustomEvent"
+        }
+      },
+      {
+        "name": "open-change",
+        "description": "Open state changed. detail: { open, reason }",
+        "type": {
+          "text": "CustomEvent"
+        }
+      },
+      {
+        "name": "skip",
+        "description": "Skip was requested.",
+        "type": {
+          "text": "CustomEvent"
+        }
+      }
+    ],
+    "slots": [
+      {
+        "name": "media",
+        "description": "Full-bleed media above the copy: an img, picture, video, or svg"
+      },
+      {
+        "name": "",
+        "description": "Body content (replaces `description`)"
+      },
+      {
+        "name": "footer",
+        "description": "Custom footer actions (replaces Skip/Back/Next)"
+      }
+    ],
+    "cssParts": [
+      {
+        "name": "dialog",
+        "description": "Native dialog root (dialog presentations)."
+      },
+      {
+        "name": "overlay",
+        "description": "Dialog backdrop element."
+      },
+      {
+        "name": "float",
+        "description": "Popover-mode panel."
+      },
+      {
+        "name": "panel",
+        "description": "Dialog-mode panel."
+      },
+      {
+        "name": "card",
+        "description": "Card container inside either panel."
+      },
+      {
+        "name": "media",
+        "description": "Full-bleed media region above the copy (hidden while the slot is empty)."
+      },
+      {
+        "name": "header",
+        "description": "Header container."
+      },
+      {
+        "name": "title",
+        "description": "Title text element."
+      },
+      {
+        "name": "step-count",
+        "description": "Visible \"Step N of M\" label beside the progress bar."
+      },
+      {
+        "name": "close",
+        "description": "Close action control."
+      },
+      {
+        "name": "body",
+        "description": "Body content container."
+      },
+      {
+        "name": "footer",
+        "description": "Footer container."
+      }
+    ],
+    "cssProperties": [
+      {
+        "name": "--tour-bg",
+        "description": "Card background color"
+      },
+      {
+        "name": "--tour-border-color",
+        "description": "Card border color"
+      },
+      {
+        "name": "--tour-max-width",
+        "description": "Card max width (default 22rem)"
+      },
+      {
+        "name": "--tour-media-max-height",
+        "description": "Media ceiling (default min(38dvh, 16rem); bottom-sheet min(26dvh, 12rem))"
+      },
+      {
+        "name": "--tour-panel-blur",
+        "description": "Backdrop blur behind the translucent card (default var(--blur-md))"
+      },
+      {
+        "name": "--tour-radius",
+        "description": "Card border radius"
+      },
+      {
+        "name": "--tour-shadow",
+        "description": "Card drop shadow"
+      }
+    ],
+    "demos": [
+      {
+        "url": "",
+        "description": "```html\n<ore-tour open title=\"Welcome\" description=\"Start here.\" step-index=\"0\" total-steps=\"3\"></ore-tour>\n<script type=\"module\">\n  import '@vielzeug/refine/tour';\n  const card = document.querySelector('ore-tour');\n  card.anchor = document.querySelector('#save-button');\n  card.addEventListener('next', () => console.log('advance'));\n</script>\n```"
+      }
+    ]
   }
 ]