@fusion.dev/helix-headless 0.100.0 → 0.102.0

package/types/svelte.d.ts

@@ -62,11 +62,14 @@ declare module 'svelte/elements' {
     'helix-headless-input': CustomElements['helix-headless-input']
     'helix-headless-kbd': CustomElements['helix-headless-kbd']
     'helix-headless-legend': CustomElements['helix-headless-legend']
+    'helix-headless-lightbox-item': CustomElements['helix-headless-lightbox-item']
+    'helix-headless-lightbox': CustomElements['helix-headless-lightbox']
     'helix-headless-line-chart': CustomElements['helix-headless-line-chart']
     'helix-headless-list-item': CustomElements['helix-headless-list-item']
     'helix-headless-list': CustomElements['helix-headless-list']
     'helix-headless-listbox': CustomElements['helix-headless-listbox']
     'helix-headless-loader': CustomElements['helix-headless-loader']
+    'helix-headless-map': CustomElements['helix-headless-map']
     'helix-headless-megamenu': CustomElements['helix-headless-megamenu']
     'helix-headless-menu-item': CustomElements['helix-headless-menu-item']
     'helix-headless-menu': CustomElements['helix-headless-menu']

package/types/vue.d.ts

@@ -57,11 +57,14 @@ import type {
   HelixHeadlessInput,
   HelixHeadlessKbd,
   HelixHeadlessLegend,
+  HelixHeadlessLightboxItem,
+  HelixHeadlessLightbox,
   HelixHeadlessLineChart,
   HelixHeadlessListItem,
   HelixHeadlessList,
   HelixHeadlessListbox,
   HelixHeadlessLoader,
+  HelixHeadlessMap,
   HelixHeadlessMegamenu,
   HelixHeadlessMenuItem,
   HelixHeadlessMenu,
@@ -155,12 +158,14 @@ import type {
   HelixFacetEvent,
   HelixResizeEvent,
   HelixShortcutEvent,
-  HelixReadEvent,
   HelixActivateEvent,
+  HelixBeforeActivateEvent,
+  HelixMapPanEvent,
+  HelixMapZoomEvent,
+  HelixReadEvent,
   HelixCompleteEvent,
   HelixBeforeCollapseEvent,
   HelixBeforeResizeEvent,
-  HelixBeforeActivateEvent,
   HelixTourAskEvent,
   HelixNextEvent,
   HelixPreviousEvent,
@@ -4361,6 +4366,119 @@ shadow root reads a table in that root rather than one in the document.
 
 export type HelixHeadlessLegendVueEvents = {};
 
+export type HelixHeadlessLightboxItemVueProps = {
+  /** Whether this is the one being shown.
+
+Written by the root, which is the only thing that sees the set. */
+  current?: (HelixHeadlessLightboxItem["current"]) | undefined;
+  /** What this item is called, for the reading that says where the reader is. */
+  label?: (HelixHeadlessLightboxItem["label"]) | undefined;
+  /** What names this item, and what `active` on the root is compared against. */
+  value?: (HelixHeadlessLightboxItem["value"]) | undefined;
+};
+
+export type HelixHeadlessLightboxItemVueEvents = {};
+
+/** `HelixHeadlessLightbox` component event */
+export type HelixHeadlessLightboxElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessLightbox,
+  E
+>;
+/** `helix-activate` event type */
+export type HelixHeadlessLightboxHelixActivateElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixActivateEvent>;
+/** `helix-before-activate` event type */
+export type HelixHeadlessLightboxHelixBeforeActivateElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixBeforeActivateEvent>;
+/** `helix-before-close` event type */
+export type HelixHeadlessLightboxHelixBeforeCloseElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixBeforeCloseEvent>;
+/** `helix-before-open` event type */
+export type HelixHeadlessLightboxHelixBeforeOpenElementEvent =
+  HelixHeadlessLightboxElementEvent<HelixBeforeOpenEvent>;
+
+export type HelixHeadlessLightboxVueProps = {
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is what a viewer with a caption worth reading
+wants. The wait is only ever about idling: whether anything else should
+keep the chrome up is the consumer's to decide with this. */
+  "idle-delay"?: (HelixHeadlessLightbox["idleDelay"] | `${number}`) | undefined;
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is what a viewer with a caption worth reading
+wants. The wait is only ever about idling: whether anything else should
+keep the chrome up is the consumer's to decide with this. */
+  idleDelay?: (HelixHeadlessLightbox["idleDelay"]) | undefined;
+  /** Accessible name for the viewer. */
+  label?: (HelixHeadlessLightbox["label"]) | undefined;
+  /** Whether walking past the end comes back to the beginning. */
+  loop?: (HelixHeadlessLightbox["loop"]) | undefined;
+  /** The reading that says where in the set the reader is, with `{index}` and
+`{count}` filled in.
+
+Announced rather than only drawn, because the picture changing under a
+reader who cannot see it is otherwise silent. A consumer who has their own
+counter in the chrome can empty this and say it themselves. */
+  "status-label"?: (HelixHeadlessLightbox["statusLabel"]) | undefined;
+  /** The reading that says where in the set the reader is, with `{index}` and
+`{count}` filled in.
+
+Announced rather than only drawn, because the picture changing under a
+reader who cannot see it is otherwise silent. A consumer who has their own
+counter in the chrome can empty this and say it themselves. */
+  statusLabel?: (HelixHeadlessLightbox["statusLabel"]) | undefined;
+  /** Which item is current, by its `value`.
+
+Not `option.active`, which is the option the keyboard is on: that is a
+different question from which one is chosen.
+
+Writing always applies, so `<helix-tabs active="one">` starts on that
+tab, and `default-active` is how markup says where to start without
+naming the current one. */
+  active?: (HelixHeadlessLightbox["active"]) | undefined;
+  /** Which item the markup declared current.
+
+Ignored once `active` is written. */
+  "default-active"?: (HelixHeadlessLightbox["defaultActive"]) | undefined;
+  /** Which item the markup declared current.
+
+Ignored once `active` is written. */
+  defaultActive?: (HelixHeadlessLightbox["defaultActive"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  open?: (HelixHeadlessLightbox["open"]) | undefined;
+  /** Whether the markup declared it open. Ignored once `open` is written. */
+  "default-open"?: (HelixHeadlessLightbox["defaultOpen"]) | undefined;
+  /** Whether the markup declared it open. Ignored once `open` is written. */
+  defaultOpen?: (HelixHeadlessLightbox["defaultOpen"]) | undefined;
+};
+
+export type HelixHeadlessLightboxVueEvents = {
+  /** Relayed, because the platform's own does not escape. */
+  close: HelixHeadlessLightboxElementEvent;
+  /** Fired once the shown item has moved, so the element already holds it. */
+  "helix-activate": HelixHeadlessLightboxHelixActivateElementEvent;
+  /** Fired before the shown item changes, and cancelable. The only way to refuse one. */
+  "helix-before-activate": HelixHeadlessLightboxHelixBeforeActivateElementEvent;
+  /** Fired before it closes, and cancelable. */
+  "helix-before-close": HelixHeadlessLightboxHelixBeforeCloseElementEvent;
+  /** Fired before it opens, and cancelable. */
+  "helix-before-open": HelixHeadlessLightboxHelixBeforeOpenElementEvent;
+  /** Says the state moved, carrying `newState` and `oldState`. */
+  toggle: HelixHeadlessLightboxElementEvent;
+};
+
 export type HelixHeadlessLineChartVueProps = {
   /** Whether a wash is drawn under each line, each from the floor on its own.
 The washes overlap rather than add up: for parts that make a total, use
@@ -4677,6 +4795,76 @@ export type HelixHeadlessLoaderVueProps = {
 
 export type HelixHeadlessLoaderVueEvents = {};
 
+/** `HelixHeadlessMap` component event */
+export type HelixHeadlessMapElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessMap,
+  E
+>;
+/** `helix-map-pan` event type */
+export type HelixHeadlessMapHelixMapPanElementEvent =
+  HelixHeadlessMapElementEvent<HelixMapPanEvent>;
+/** `helix-map-zoom` event type */
+export type HelixHeadlessMapHelixMapZoomElementEvent =
+  HelixHeadlessMapElementEvent<HelixMapZoomEvent>;
+
+export type HelixHeadlessMapVueProps = {
+  /** What the control that fills the screen is called. */
+  "fullscreen-label"?: (HelixHeadlessMap["fullscreenLabel"]) | undefined;
+  /** What the control that fills the screen is called. */
+  fullscreenLabel?: (HelixHeadlessMap["fullscreenLabel"]) | undefined;
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is the default: a map's controls are how a keyboard
+reader operates it, and chrome that hides itself by default would be this
+component undoing its own argument. Set it for a display map nobody drives. */
+  "idle-delay"?: (HelixHeadlessMap["idleDelay"] | `${number}`) | undefined;
+  /** How long the reader may be still before the chrome hides, in milliseconds.
+
+Zero keeps it up, which is the default: a map's controls are how a keyboard
+reader operates it, and chrome that hides itself by default would be this
+component undoing its own argument. Set it for a display map nobody drives. */
+  idleDelay?: (HelixHeadlessMap["idleDelay"]) | undefined;
+  /** Accessible name for the map, which is the one thing a consumer must write.
+
+There is no sensible default. "Map" names the widget rather than the place,
+and a reader meeting three of them on a page learns nothing from hearing the
+same word three times. */
+  label?: (HelixHeadlessMap["label"]) | undefined;
+  /** What the controls are called, for a page not in English. */
+  "pan-label"?: (HelixHeadlessMap["panLabel"]) | undefined;
+  /** What the controls are called, for a page not in English. */
+  panLabel?: (HelixHeadlessMap["panLabel"]) | undefined;
+  /** How far one press moves the map, as a fraction of what is on screen.
+
+A fraction rather than a distance, because this frame does not know the
+scale of what is inside it: a quarter of the viewport is the same gesture at
+street level and at country level, and a consumer who wants metres can
+multiply by their own. */
+  "pan-step"?: (HelixHeadlessMap["panStep"] | `${number}`) | undefined;
+  /** How far one press moves the map, as a fraction of what is on screen.
+
+A fraction rather than a distance, because this frame does not know the
+scale of what is inside it: a quarter of the viewport is the same gesture at
+street level and at country level, and a consumer who wants metres can
+multiply by their own. */
+  panStep?: (HelixHeadlessMap["panStep"]) | undefined;
+  /** What the zoom controls are called. */
+  "zoom-in-label"?: (HelixHeadlessMap["zoomInLabel"]) | undefined;
+  /** What the zoom controls are called. */
+  zoomInLabel?: (HelixHeadlessMap["zoomInLabel"]) | undefined;
+  /** What the zoom control that goes the other way is called. */
+  "zoom-out-label"?: (HelixHeadlessMap["zoomOutLabel"]) | undefined;
+  /** What the zoom control that goes the other way is called. */
+  zoomOutLabel?: (HelixHeadlessMap["zoomOutLabel"]) | undefined;
+};
+
+export type HelixHeadlessMapVueEvents = {
+  /** The reader asked the map to move. Answer it against your own map. */
+  "helix-map-pan": HelixHeadlessMapHelixMapPanElementEvent;
+  /** The reader asked the map to zoom, by a direction rather than to a level. */
+  "helix-map-zoom": HelixHeadlessMapHelixMapZoomElementEvent;
+};
+
 /** `HelixHeadlessMegamenu` component event */
 export type HelixHeadlessMegamenuElementEvent<E = Event> = TypedEvent<
   HelixHeadlessMegamenu,
@@ -9673,6 +9861,18 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLegendVueProps,
     HelixHeadlessLegendVueEvents
   >;
+  /** A wrapper around whatever the consumer opened, which is the whole of what it is: a picture, a frame of video, a chart. The family shows one at a time and this is how it says which, so the content stays the consumer's and the arithmetic stays the root's.  Hidden rather than unmounted while another item is current, for the reason 'TabPanel' gives: what is in the markup is what a crawler reads and what a server sent, and an '<img>' that has already decoded does not decode again when the reader walks back to it. */
+  "helix-headless-lightbox-item": DefineCustomElement<
+    HelixHeadlessLightboxItem,
+    HelixHeadlessLightboxItemVueProps,
+    HelixHeadlessLightboxItemVueEvents
+  >;
+  /** **A lightbox is chrome around a picture rather than a picture.** It draws nothing of its own: what it shows is whatever the consumer opened, so this earns its place on the frame, the keyboard and the reading that says where in the set the reader is.  **The modal half is the platform's.** A real '<dialog>' opened with 'showModal()' brings the top layer, a backdrop, Escape and 'inert' behind it, and this repository has already removed one hand-written focus trap for being worse than that: 'inert' on the rest of the document is something no JavaScript trap can achieve. Every way it can close comes back through 'requestOpen', which is what 'Dialog' and 'Drawer' both do and for the reason they both give.  **The set is this component's own and not 'Carousel''s.** A carousel is a track: a scroller with snap points, per-view arithmetic and stops it can rest between. A lightbox shows one thing at a time and has no track, so what it needs is which item is current, which is 'active' and the same pair 'Tabs' uses. The arrow keys move the picture under a reader whose focus stays in the dialog, which is also why 'KeyboardNavigationController' is not the right tool: that one moves focus between focusable items, and these are pictures.  **Chrome hides while the reader is still**, on 'IdleController', and comes back on a pointer move or a focus. 'fullscreen' is 'FullscreenController', the same pair 'Video' holds and the only two it shares. */
+  "helix-headless-lightbox": DefineCustomElement<
+    HelixHeadlessLightbox,
+    HelixHeadlessLightboxVueProps,
+    HelixHeadlessLightboxVueEvents
+  >;
   /** The chart for a shape rather than for a quantity, which is what decides the one thing a bar chart is not allowed to do.  **It measures from its own range and not from zero, deliberately.** 'BarChart' refuses that switch because a bar's length *is* its value, so a baseline anywhere else makes the lengths proportional to nothing. A line claims no such thing: it says where the readings went, and forcing zero into the range of a series that moves between 980 and 1020 flattens the entire shape into a rule across the top of the box. The two rules are opposite because the two charts answer opposite questions, and 'zero' is here for the case where the distance from nothing is the point.  **One scale across every series**, the same as the bar chart, because two series drawn to different scales are two charts sharing a picture.  **Not the chart for a total made of parts.** 'area' washes each series from the floor on its own, so they overlap; 'Area Chart' stacks them, so the top edge is the total and each band is a share. A line chart answers how each series moved, an area chart how the whole is made up.  **The labels are HTML beside the drawing rather than '<text>' inside it**, for the reason 'BarChart' records: an '<svg>' that fills its box scales its type with everything else, the same 'font-size' arriving at 10px in a narrow chart and 43px in a wide one, and there is no non-scaling-font to answer it the way 'vector-effect' answers strokes.  The table is the accessible representation and this drawing is 'aria-hidden'. A reader who wants the numbers gets the numbers, not a described picture. */
   "helix-headless-line-chart": DefineCustomElement<
     HelixHeadlessLineChart,
@@ -9703,6 +9903,12 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLoaderVueProps,
     HelixHeadlessLoaderVueEvents
   >;
+  /** **Helix draws no map.** There are no tiles here, no projection and no network, and there should not be: a tile renderer is a library, and what a design system can add to MapLibre or Leaflet is the frame. The consumer slots their map and this owns the box, the name, the controls and the way out, which is the shape 'VideoPlaylist' uses for a player it never renders.  **The accessibility argument is the reason this exists**, and it was measured rather than assumed: a map embedded the ordinary way is a canvas with no role and no name, and it has *no node at all* in the accessibility tree. A reader using a screen reader does not walk past it so much as never meet it. A named region with controls in it is the whole of the difference.  **The controls are buttons, and that is a deliberate choice against arrow keys.** Arrows work here too, but what a screen reader does with them is not ours to decide: macOS passes them through, Windows readers hold them for their own reading mode unless a page takes 'role="application"', which costs the reader their normal way of reading everything else in the frame. A button is findable and operable in every screen reader on every platform without that bargain, so panning and zooming are buttons first and keys second.  **Nothing here moves the map.** Both controls ask, through 'helix-map-pan' and 'helix-map-zoom', and the consumer answers against whatever they slotted. A frame that moved the map would have to know whose map it was. */
+  "helix-headless-map": DefineCustomElement<
+    HelixHeadlessMap,
+    HelixHeadlessMapVueProps,
+    HelixHeadlessMapVueEvents
+  >;
   /** **A disclosure, not a menu, and that is the whole design.** 'role="menu"' and 'menuitem' are for an application's commands: they take over the arrow keys, announce "menu" to a reader who asked for navigation, and put every link inside a role that is not a link. This is a button that shows and hides a region of the consumer's own anchors, which leaves a middle click, a modified click and the status bar working. 'Menu' remains right for a row of commands.  **It renders no links.** A router renders its own anchor and cannot render one inside this shadow root, so the panel is a slot and what goes in it is the lists and headings the consumer wrote.  **It opens on hover, and a press is always the fallback.** 'open-on' says which, and hover is the resting value because a nav bar is where a reader expects to sweep along a row and see each section. */
   "helix-headless-megamenu": DefineCustomElement<
     HelixHeadlessMegamenu,