@vizejs/ui 0.443.0 → 0.457.0

package/registry/files/families/feedback/progress-bar/progress-bar-state.ts

@@ -24,6 +24,8 @@ export interface ProgressBarStateOptions {
 
   /**
    * Raw maximum. Values less than or equal to `min` are repaired to `min + 100`.
+   * If that addition rounds back to `min`, the collapsed finite range reports
+   * zero ratio/percent and invalid state without changing the completion policy.
    *
    * @default PROGRESS_BAR_DEFAULT_MAX
    */
@@ -66,12 +68,20 @@ export function getProgressBarState(
     invalid = invalid || options.max != null;
     max = min + PROGRESS_BAR_DEFAULT_MAX;
   }
+  invalid = invalid || max === min;
 
   const value = finite(options.value) ? clamp(options.value, min, max) : null;
   invalid =
     invalid || (options.value != null && (!finite(options.value) || options.value !== value));
   const indeterminate = value === null;
-  const ratio = indeterminate ? null : (value - min) / (max - min);
+  const span = max - min;
+  const ratio = indeterminate
+    ? null
+    : span === 0
+      ? 0
+      : Number.isFinite(span)
+        ? (value - min) / span
+        : (value / 2 - min / 2) / (max / 2 - min / 2);
   const percent = ratio === null ? null : ratio * 100;
   const complete = value !== null && value >= max;
 

package/registry/files/families/feedback/progress-bar/progress-bar-types.ts

@@ -38,7 +38,11 @@ export interface ProgressBarProps {
   /** Lower bound. Non-finite values fall back to 0. */
   readonly min?: number | null;
 
-  /** Upper bound. Values less than or equal to `min` are repaired to `min + 100`. */
+  /**
+   * Upper bound. Values less than or equal to `min` are repaired to `min + 100`.
+   * If that addition rounds back to `min`, the collapsed finite range reports
+   * zero ratio/percent and invalid state without changing the completion policy.
+   */
   readonly max?: number | null;
 
   /** Reading direction for inline-start fill and indeterminate motion. */
@@ -71,7 +75,7 @@ export interface ProgressBarSlotState {
   /** Finite lower bound. */
   readonly min: number;
 
-  /** Finite upper bound, always greater than `min`. */
+  /** Finite upper bound, equal to `min` only when the default repair cannot advance it. */
   readonly max: number;
 
   /** Current completion percentage from 0 to 100, or `null` when indeterminate. */

package/registry/files/families/feedback/progress-bar/progress-bar.vue

@@ -46,7 +46,12 @@ const {
   /** Lower bound for the progress range. @default 0 */
   readonly min?: number | null;
 
-  /** Upper bound for the progress range. @default 100 */
+  /**
+   * Upper bound. Values less than or equal to `min` are repaired to `min + 100`.
+   * If that addition rounds back to `min`, the collapsed finite range reports
+   * zero ratio/percent and invalid state without changing the completion policy.
+   * @default 100
+   */
   readonly max?: number | null;
 
   /** Reading direction for inline-start fill and indeterminate motion. @default "ltr" */

package/registry/files/families/menus/menu/menu-types.ts

@@ -24,7 +24,7 @@ export type MenuDirection = "ltr" | "rtl";
  * Which surface owns a menu tree. The kind only changes defaults and data hooks;
  * every kind shares the same keyboard, focus, and dismissal core.
  */
-export type MenuKind = "context-menu" | "dropdown-menu" | "menu" | "menubar";
+export type MenuKind = "context-menu" | "dropdown-menu" | "menu" | "menubar" | "split-button";
 
 /**
  * Where focus lands when a menu opens.

package/registry/files/families/navigation/app-bar/app-bar-types.ts

@@ -0,0 +1,32 @@
+/** Scroll container an AppBar follows: an element, a selector, or `null` for the window. */
+export type AppBarTarget = HTMLElement | string | null;
+
+/** Stable visibility state exposed for consumer-owned styling and tests. */
+export type AppBarState = "visible" | "hidden";
+
+/** State exposed to every AppBar slot. */
+export interface AppBarSlotState {
+  /** Whether the followed container has scrolled past `elevateThreshold`. */
+  readonly elevated: boolean;
+
+  /** Whether `hideOnScroll` currently asks the consumer to move the bar out of view. */
+  readonly hidden: boolean;
+
+  /** Stable visibility token for styling and tests. */
+  readonly state: AppBarState;
+
+  /** Current scroll offset of the followed container in CSS pixels. */
+  readonly scrollTop: number;
+}
+
+/** Public instance exposed by AppBar. */
+export interface AppBarExpose extends AppBarSlotState {
+  /** Rendered root element. */
+  readonly element: HTMLElement | null;
+
+  /** Bring a hidden bar back into view. */
+  readonly show: () => void;
+
+  /** Re-read the scroll offset, for containers that scroll without a scroll event. */
+  readonly refresh: () => number;
+}

package/registry/files/families/navigation/app-bar/app-bar.ts

@@ -0,0 +1,3 @@
+/** Top application bar: a header landmark that reports scroll elevation and can hide while scrolling down. */
+export { default as AppBar } from "./app-bar.vue";
+export type { AppBarExpose, AppBarSlotState, AppBarState, AppBarTarget } from "./app-bar-types.ts";

package/registry/files/families/navigation/app-bar/app-bar.vue

@@ -0,0 +1,215 @@
+<script setup lang="ts">
+import { computed, onMounted, onScopeDispose, shallowRef, useTemplateRef, watch } from "vue";
+import type { ComputedRef, ShallowRef } from "vue";
+
+import type { AppBarExpose, AppBarSlotState, AppBarState, AppBarTarget } from "./app-bar-types.ts";
+
+const {
+  as = "header",
+  target = null,
+  elevateThreshold = 0,
+  hideOnScroll = false,
+  hideThreshold = 64,
+  ariaLabel = undefined,
+  ariaLabelledby = undefined,
+} = defineProps<{
+  /**
+   * Host element. A top-level `header` is the page's banner landmark; use `div`
+   * when the bar sits inside another landmark that already has a header.
+   *
+   * @default "header"
+   */
+  readonly as?: "header" | "div";
+
+  /**
+   * Scroll container to follow: an element, a selector, or `null` for the window.
+   *
+   * @default null
+   */
+  readonly target?: AppBarTarget;
+
+  /**
+   * Scroll offset in CSS pixels past which the bar reports `elevated`.
+   *
+   * @default 0
+   */
+  readonly elevateThreshold?: number;
+
+  /**
+   * Report `hidden` while the container scrolls down, and visible again as soon as it scrolls up.
+   *
+   * @default false
+   */
+  readonly hideOnScroll?: boolean;
+
+  /**
+   * Scroll offset in CSS pixels before `hideOnScroll` may hide the bar.
+   *
+   * @default 64
+   */
+  readonly hideThreshold?: number;
+
+  /**
+   * Accessible name of the landmark when no visible title labels it.
+   *
+   * @default undefined
+   */
+  readonly ariaLabel?: string;
+
+  /**
+   * Ids that label the landmark (overrides `ariaLabel`).
+   *
+   * @default undefined
+   */
+  readonly ariaLabelledby?: string;
+}>();
+
+const emit = defineEmits<{
+  /** Fired when `hideOnScroll` hides or reveals the bar. */
+  "visibility-change": [hidden: boolean];
+}>();
+
+defineSlots<{
+  /** Leading content such as a navigation or back button. */
+  start?(props: AppBarSlotState): unknown;
+  /** Title and main content. */
+  default?(props: AppBarSlotState): unknown;
+  /** Trailing actions. */
+  end?(props: AppBarSlotState): unknown;
+}>();
+
+const element = useTemplateRef<HTMLElement>("element");
+const scrollTop = shallowRef(0);
+const hidden = shallowRef(false);
+const focusWithin = shallowRef(false);
+const finite = (value: number, fallback: number) =>
+  Number.isFinite(value) ? Math.max(0, value) : fallback;
+const elevated = computed(() => scrollTop.value > finite(elevateThreshold, 0));
+const state = computed<AppBarState>(() => (hidden.value ? "hidden" : "visible"));
+const slotState = computed<AppBarSlotState>(() => ({
+  elevated: elevated.value,
+  hidden: hidden.value,
+  scrollTop: scrollTop.value,
+  state: state.value,
+}));
+let container: HTMLElement | Window | null = null;
+
+function setHidden(next: boolean): void {
+  if (hidden.value === next) return;
+  hidden.value = next;
+  emit("visibility-change", next);
+}
+
+function resolveContainer(): HTMLElement | Window | null {
+  const ownerDocument = element.value?.ownerDocument;
+  if (!ownerDocument) return null;
+  if (target === null) return ownerDocument.defaultView;
+  if (typeof target !== "string") return target;
+  const found = ownerDocument.querySelector(target);
+  return found instanceof HTMLElement ? found : null;
+}
+
+function readOffset(source: HTMLElement | Window): number {
+  const offset = "scrollY" in source ? source.scrollY : source.scrollTop;
+  return Number.isFinite(offset) ? Math.max(0, offset) : 0;
+}
+
+function refresh(): number {
+  const previous = scrollTop.value;
+  const next = container === null ? 0 : readOffset(container);
+  scrollTop.value = next;
+  if (!hideOnScroll || focusWithin.value) setHidden(false);
+  else if (next < previous || next <= finite(hideThreshold, 64)) setHidden(false);
+  else if (next > previous) setHidden(true);
+  return next;
+}
+
+function onScroll(): void {
+  refresh();
+}
+
+function detach(): void {
+  container?.removeEventListener("scroll", onScroll);
+  container = null;
+}
+
+function attach(): void {
+  detach();
+  container = resolveContainer();
+  container?.addEventListener("scroll", onScroll, { passive: true });
+  scrollTop.value = container === null ? 0 : readOffset(container);
+}
+
+function onFocusin(): void {
+  focusWithin.value = true;
+  setHidden(false);
+}
+
+function onFocusout(event: FocusEvent): void {
+  const next = event.relatedTarget;
+  focusWithin.value = next instanceof Node && element.value?.contains(next) === true;
+}
+
+function show(): void {
+  setHidden(false);
+}
+
+onMounted(attach);
+watch(
+  () => target,
+  () => attach(),
+);
+watch(
+  () => hideOnScroll,
+  (enabled) => {
+    if (!enabled) setHidden(false);
+  },
+);
+onScopeDispose(detach);
+
+defineExpose({
+  element,
+  elevated,
+  hidden,
+  refresh,
+  scrollTop,
+  show,
+  state,
+} satisfies Omit<AppBarExpose, "element" | "elevated" | "hidden" | "scrollTop" | "state"> & {
+  readonly element: typeof element;
+  readonly elevated: ComputedRef<boolean>;
+  readonly hidden: Readonly<ShallowRef<boolean>>;
+  readonly scrollTop: Readonly<ShallowRef<number>>;
+  readonly state: ComputedRef<AppBarState>;
+});
+</script>
+
+<template>
+  <component
+    :is="as"
+    ref="element"
+    :aria-label="ariaLabelledby === undefined ? ariaLabel : undefined"
+    :aria-labelledby
+    part="root"
+    data-vize-ui="app-bar"
+    :data-state="state"
+    :data-elevated="elevated ? 'true' : undefined"
+    :data-hidden="hidden ? 'true' : undefined"
+    @focusin="onFocusin"
+    @focusout="onFocusout"
+  >
+    <div v-if="$slots.start" part="start" data-vize-ui="app-bar-start">
+      <slot name="start" v-bind="slotState" />
+    </div>
+    <div part="content" data-vize-ui="app-bar-content">
+      <slot v-bind="slotState" />
+    </div>
+    <div v-if="$slots.end" part="end" data-vize-ui="app-bar-end">
+      <slot name="end" v-bind="slotState" />
+    </div>
+  </component>
+</template>
+
+<style scoped>
+/* Headless by design. Position, elevation, and the hide transition are consumer-owned. */
+</style>

package/registry/files/families/navigation/app-bar/examples/app-bar-basic.vue

@@ -0,0 +1,21 @@
+<!-- Top app bar with a menu button, a title, and a search action that hides while scrolling down. -->
+<script setup lang="ts">
+import { useId } from "vue";
+import { AppBar } from "../app-bar.ts";
+
+const titleId = useId();
+</script>
+
+<template>
+  <AppBar hide-on-scroll :aria-labelledby="titleId">
+    <template #start>
+      <button type="button" aria-label="Open navigation">≡</button>
+    </template>
+    <template #default="{ elevated }">
+      <span :id="titleId" :data-elevated="elevated ? 'true' : undefined">Inbox</span>
+    </template>
+    <template #end>
+      <button type="button">Search</button>
+    </template>
+  </AppBar>
+</template>

package/registry/files/families/navigation/navigation-rail/examples/navigation-rail-basic.vue

@@ -0,0 +1,21 @@
+<!-- Collapsible side rail with three destinations and an unread badge. -->
+<script setup lang="ts">
+import { ref } from "vue";
+
+import { NavigationRail, NavigationRailItem, NavigationRailToggle } from "../navigation-rail.ts";
+
+const destinations = ["home", "search", "inbox"] as const;
+const current = ref<(typeof destinations)[number]>("home");
+const expanded = ref(false);
+</script>
+
+<template>
+  <NavigationRail v-model="current" v-model:expanded="expanded" :destinations>
+    <NavigationRailToggle aria-label="Toggle navigation labels">
+      {{ expanded ? "«" : "»" }}
+    </NavigationRailToggle>
+    <NavigationRailItem value="home">Home</NavigationRailItem>
+    <NavigationRailItem value="search">Search</NavigationRailItem>
+    <NavigationRailItem value="inbox" :badge="3">Inbox</NavigationRailItem>
+  </NavigationRail>
+</template>

package/registry/files/families/navigation/navigation-rail/navigation-rail-context.ts

@@ -0,0 +1,17 @@
+import type { ComputedRef } from "vue";
+
+import { createContext } from "../../foundations/context/context.ts";
+
+/** Type-erased NavigationRail state shared with items and the toggle. */
+export interface NavigationRailContextValue {
+  /** Id of the navigation landmark, referenced by the toggle's `aria-controls`. */
+  readonly id: ComputedRef<string>;
+  readonly active: ComputedRef<string | undefined>;
+  /** Whether destinations show their labels beside the icons. */
+  readonly expanded: ComputedRef<boolean>;
+  readonly select: (value: string, event: MouseEvent) => void;
+  readonly setExpanded: (value: boolean) => void;
+}
+
+/** Typed context shared by NavigationRail, its items, and its toggle. */
+export const navigationRailContext = createContext<NavigationRailContextValue>("NavigationRail");

package/registry/files/families/navigation/navigation-rail/navigation-rail-item.vue

@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import { computed } from "vue";
+
+import { navigationRailContext } from "./navigation-rail-context.ts";
+
+const {
+  value,
+  href = undefined,
+  disabled = false,
+  badge = undefined,
+} = defineProps<{
+  /**
+   * Destination value; must be one of the root `destinations`.
+   *
+   * @default required
+   */
+  readonly value: string;
+
+  /**
+   * Link target. With `href` the item renders an `<a>`, otherwise a `<button>`.
+   *
+   * @default undefined
+   */
+  readonly href?: string;
+
+  /**
+   * Disable the destination.
+   *
+   * @default false
+   */
+  readonly disabled?: boolean;
+
+  /**
+   * Badge text rendered with the label (for example an unread count).
+   *
+   * @default undefined
+   */
+  readonly badge?: string | number;
+}>();
+
+defineSlots<{
+  /** Icon and label contents with the active and expanded state. */
+  default(props: { readonly active: boolean; readonly expanded: boolean }): unknown;
+  /** Visual badge contents; defaults to the `badge` text. */
+  badge?(props: { readonly badge: string | number }): unknown;
+}>();
+
+const context = navigationRailContext.use();
+const active = computed(() => context.active.value === value);
+// Script-capable URLs never render; only safe hrefs are bound (spread keeps the attribute absent).
+const unsafeHref = /^\s*(?:javascript|vbscript|data):/i;
+const linkAttributes = computed(() =>
+  href === undefined || disabled || unsafeHref.test(href) ? {} : { href },
+);
+
+function onClick(event: MouseEvent): void {
+  if (disabled) {
+    event.preventDefault();
+    return;
+  }
+  context.select(value, event);
+}
+</script>
+
+<template>
+  <component
+    :is="href === undefined ? 'button' : 'a'"
+    :type="href === undefined ? 'button' : undefined"
+    v-bind="linkAttributes"
+    :disabled="href === undefined ? disabled : undefined"
+    :aria-disabled="href !== undefined && disabled ? 'true' : undefined"
+    :aria-current="active ? 'page' : undefined"
+    part="item"
+    data-vize-ui="navigation-rail-item"
+    :data-value="value"
+    :data-state="active ? 'active' : 'inactive'"
+    :data-expanded="context.expanded.value ? 'true' : 'false'"
+    @click="onClick"
+  >
+    <slot :active :expanded="context.expanded.value" />
+    <span v-if="badge !== undefined" part="badge" data-vize-ui="navigation-rail-badge">
+      <slot name="badge" :badge>{{ badge }}</slot>
+    </span>
+  </component>
+</template>
+
+<style scoped>
+/* Headless by design. Native CSS remains entirely consumer-owned. */
+</style>

package/registry/files/families/navigation/navigation-rail/navigation-rail-toggle.vue

@@ -0,0 +1,50 @@
+<script setup lang="ts">
+import { navigationRailContext } from "./navigation-rail-context.ts";
+
+const { disabled = false, ariaLabel = undefined } = defineProps<{
+  /**
+   * Disable expanding and collapsing.
+   *
+   * @default false
+   */
+  readonly disabled?: boolean;
+
+  /**
+   * Accessible name when the toggle renders only an icon.
+   *
+   * @default undefined
+   */
+  readonly ariaLabel?: string;
+}>();
+
+defineSlots<{
+  /** Toggle contents with the expanded state. */
+  default(props: { readonly expanded: boolean }): unknown;
+}>();
+
+const context = navigationRailContext.use();
+
+function onClick(): void {
+  if (!disabled) context.setExpanded(!context.expanded.value);
+}
+</script>
+
+<template>
+  <button
+    type="button"
+    :disabled
+    :aria-label
+    :aria-expanded="context.expanded.value ? 'true' : 'false'"
+    :aria-controls="context.id.value"
+    part="toggle"
+    data-vize-ui="navigation-rail-toggle"
+    :data-state="context.expanded.value ? 'expanded' : 'collapsed'"
+    @click="onClick"
+  >
+    <slot :expanded="context.expanded.value" />
+  </button>
+</template>
+
+<style scoped>
+/* Headless by design. Native CSS remains entirely consumer-owned. */
+</style>

package/registry/files/families/navigation/navigation-rail/navigation-rail-types.ts

@@ -0,0 +1,23 @@
+/** State exposed to the NavigationRail default slot. */
+export interface NavigationRailSlotState<Value extends string = string> {
+  /** Current destination, or `undefined` before one is chosen. */
+  readonly active: Value | undefined;
+
+  /** Whether destinations show their labels beside the icons. */
+  readonly expanded: boolean;
+}
+
+/** Imperative surface exposed by NavigationRail. */
+export interface NavigationRailExpose {
+  /** Id of the navigation landmark. */
+  readonly id: string;
+
+  /** Whether destinations show their labels beside the icons. */
+  readonly expanded: boolean;
+
+  /** Request an expanded value. */
+  readonly setExpanded: (value: boolean) => void;
+
+  /** Flip the expanded value. */
+  readonly toggle: () => void;
+}

package/registry/files/families/navigation/navigation-rail/navigation-rail.ts

@@ -0,0 +1,11 @@
+/**
+ * Side navigation rail: a labelled navigation landmark of top-level
+ * destinations whose current one carries `aria-current="page"`, with an
+ * optional expanded state that shows labels beside the icons.
+ */
+export { default as NavigationRail } from "./navigation-rail.vue";
+/** Destination link or button inside NavigationRail. */
+export { default as NavigationRailItem } from "./navigation-rail-item.vue";
+/** Button that expands or collapses the rail. */
+export { default as NavigationRailToggle } from "./navigation-rail-toggle.vue";
+export type { NavigationRailExpose, NavigationRailSlotState } from "./navigation-rail-types.ts";