@vizejs/ui 0.443.0 → 0.454.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/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";

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

@@ -0,0 +1,156 @@
+<script setup lang="ts" generic="Value extends string">
+import { computed } from "vue";
+import type { ComputedRef } from "vue";
+
+import { useControllableState } from "../../foundations/controllable-state/controllable-state.ts";
+import { useDeterministicId } from "../../foundations/id/deterministic-id.ts";
+import { navigationRailContext } from "./navigation-rail-context.ts";
+import type { NavigationRailExpose, NavigationRailSlotState } from "./navigation-rail-types.ts";
+
+const {
+  destinations,
+  id = undefined,
+  modelValue = undefined,
+  defaultValue = undefined,
+  expanded = undefined,
+  defaultExpanded = false,
+  ariaLabel = "Primary",
+  ariaLabelledby = undefined,
+} = defineProps<{
+  /**
+   * Destination values in order; their literal union types `v-model` and `select`.
+   *
+   * @default required
+   */
+  readonly destinations: readonly Value[];
+
+  /**
+   * Consumer-owned id. `null` and `undefined` select a deterministic fallback.
+   *
+   * @default undefined
+   */
+  readonly id?: string | null;
+
+  /**
+   * Controlled active destination. `undefined` selects uncontrolled behavior.
+   *
+   * @default undefined
+   */
+  readonly modelValue?: Value;
+
+  /**
+   * Initial uncontrolled destination.
+   *
+   * @default undefined
+   */
+  readonly defaultValue?: Value;
+
+  /**
+   * Controlled expanded state. `undefined` selects uncontrolled behavior.
+   *
+   * @default undefined
+   */
+  readonly expanded?: boolean;
+
+  /**
+   * Initial expanded state for uncontrolled use.
+   *
+   * @default false
+   */
+  readonly defaultExpanded?: boolean;
+
+  /**
+   * Accessible name of the navigation landmark.
+   *
+   * @default "Primary"
+   */
+  readonly ariaLabel?: string;
+
+  /**
+   * Ids that label the navigation landmark (overrides `ariaLabel`).
+   *
+   * @default undefined
+   */
+  readonly ariaLabelledby?: string;
+}>();
+
+const emit = defineEmits<{
+  /** Fired when an item requests to become the active destination. */
+  "update:modelValue": [value: Value];
+
+  /** Fired after an item is activated, with its value and the native click. */
+  select: [value: Value, nativeEvent: MouseEvent];
+
+  /** Fired with the requested expanded value (supports `v-model:expanded`). */
+  "update:expanded": [value: boolean];
+}>();
+
+defineSlots<{
+  /** Toggle and NavigationRailItem destinations with the active value and expanded state. */
+  default(props: NavigationRailSlotState<Value>): unknown;
+}>();
+
+const railId = useDeterministicId({ id: () => id, hint: "navigation-rail" });
+const state = useControllableState<Value | undefined>({
+  value: () => modelValue,
+  defaultValue: () => defaultValue,
+  onChange: (value) => {
+    if (value !== undefined) emit("update:modelValue", value);
+  },
+});
+const expandedState = useControllableState<boolean>({
+  value: () => expanded,
+  defaultValue: () => defaultExpanded,
+  onChange: (value) => emit("update:expanded", value),
+});
+const isExpanded = computed(() => expandedState.value.value);
+
+function setExpanded(value: boolean): void {
+  expandedState.set(value);
+}
+
+function toggle(): void {
+  expandedState.set(!expandedState.value.value);
+}
+
+navigationRailContext.provide({
+  id: railId,
+  active: computed(() => state.value.value),
+  expanded: isExpanded,
+  select: (value: string, event: MouseEvent) => {
+    const typed = destinations.find((destination) => destination === value);
+    if (typed === undefined) return;
+    state.set(typed);
+    emit("select", typed, event);
+  },
+  setExpanded,
+});
+
+defineExpose({
+  expanded: isExpanded,
+  id: railId,
+  setExpanded,
+  toggle,
+} satisfies Omit<NavigationRailExpose, "expanded" | "id"> & {
+  readonly expanded: ComputedRef<boolean>;
+  readonly id: ComputedRef<string>;
+});
+</script>
+
+<template>
+  <nav
+    :id="railId"
+    :aria-label="ariaLabelledby === undefined ? ariaLabel : undefined"
+    :aria-labelledby
+    part="root"
+    data-vize-ui="navigation-rail"
+    :data-count="destinations.length"
+    :data-expanded="isExpanded ? 'true' : 'false'"
+  >
+    <slot :active="state.value.value" :expanded="isExpanded" />
+  </nav>
+</template>
+
+<style scoped>
+/* Headless by design. Pin with position: sticky or fixed and pad with SafeArea. */
+</style>