@vizejs/ui 0.426.3 → 0.427.0

package/registry/files/families/actions/share-button/share-button.vue

@@ -0,0 +1,251 @@
+<script setup lang="ts">
+import { computed, shallowRef, toRaw, useTemplateRef } from "vue";
+import type { ComputedRef, ShallowRef } from "vue";
+
+import type {
+  ShareButtonAction,
+  ShareButtonElement,
+  ShareButtonEmits,
+  ShareButtonExpose,
+  ShareButtonPayload,
+  ShareButtonProps,
+  ShareButtonSlotState,
+  ShareButtonState,
+  ShareButtonType,
+} from "./share-button-types.ts";
+
+type ShareButtonKeyboardPhase = "keydown" | "keyup";
+type ShareButtonKeyboardAction = "activate" | "prevent" | "ignore";
+
+type MutableShareButtonPayload = {
+  title?: string;
+  text?: string;
+  url?: string;
+  files?: File[];
+};
+
+type ShareButtonPayloadSource = {
+  readonly title: string | undefined;
+  readonly text: string | undefined;
+  readonly url: string | undefined;
+  readonly files: File[] | undefined;
+};
+
+type PlatformNavigatorWithShare = {
+  readonly share?: (payload: ShareButtonPayload) => void | Promise<void>;
+};
+
+const SHARE_BUTTON_ACTION_UNAVAILABLE = "VIZE_UI_SHARE_BUTTON_ACTION_UNAVAILABLE";
+
+const {
+  as = "button",
+  native = undefined,
+  type = "button",
+  disabled = false,
+  title = undefined,
+  text = undefined,
+  url = undefined,
+  files = undefined,
+  idleLabel = "Share",
+  sharingLabel = "Sharing",
+  sharedLabel = "Shared",
+  errorLabel = "Share failed",
+  ariaLabel = undefined,
+  ariaLabelledby = undefined,
+  ariaDescribedby = undefined,
+  action = undefined,
+} = defineProps<ShareButtonProps>();
+
+defineSlots<{
+  /** Renders button contents with the current share state. */
+  default(props: ShareButtonSlotState): unknown;
+}>();
+
+const emit = defineEmits<ShareButtonEmits>();
+
+const element = useTemplateRef<ShareButtonElement>("element");
+const stateValue = shallowRef<ShareButtonState>("idle");
+const isNativeButton = computed(() => native ?? as === "button");
+const buttonType = computed<ShareButtonType>(() => type);
+const disabledValue = computed(() => disabled);
+const sharingValue = computed(() => stateValue.value === "sharing");
+const unavailable = computed(() => disabledValue.value || sharingValue.value);
+const actionValue = computed<ShareButtonAction>(() => toRaw(action ?? shareWithNavigator));
+const payloadValue = computed<ShareButtonPayload>(() =>
+  normalizeSharePayload({ files, text, title, url }),
+);
+const label = computed(() =>
+  stateValue.value === "sharing"
+    ? sharingLabel
+    : stateValue.value === "shared"
+      ? sharedLabel
+      : stateValue.value === "error"
+        ? errorLabel
+        : idleLabel,
+);
+const tabIndex = computed(() => {
+  if (isNativeButton.value) return undefined;
+  return disabledValue.value ? -1 : 0;
+});
+const ariaLabelValue = computed(() => (hasText(ariaLabel) ? ariaLabel : undefined));
+const ariaLabelledbyValue = computed(() => (hasText(ariaLabelledby) ? ariaLabelledby : undefined));
+const slotState = computed<ShareButtonSlotState>(() => ({
+  disabled: disabledValue.value,
+  label: label.value,
+  payload: payloadValue.value,
+  sharing: sharingValue.value,
+  state: stateValue.value,
+  unavailable: unavailable.value,
+}));
+
+function onClick(event: MouseEvent): void {
+  if (unavailable.value) {
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    return;
+  }
+
+  void runShareAction(actionValue.value, payloadValue.value, event);
+}
+
+async function runShareAction(
+  submittedAction: ShareButtonAction,
+  submittedPayload: ShareButtonPayload,
+  event: MouseEvent,
+): Promise<void> {
+  stateValue.value = "sharing";
+  try {
+    await submittedAction(submittedPayload, event);
+    stateValue.value = "shared";
+    emit("share", submittedPayload, event);
+  } catch (error) {
+    stateValue.value = "error";
+    emit("error", error, submittedPayload, event);
+  }
+}
+
+function onKeyboard(event: KeyboardEvent, phase: ShareButtonKeyboardPhase): void {
+  if (isNativeButton.value) return;
+  const keyboardAction = getShareButtonKeyboardAction(event.key, phase);
+  if (keyboardAction === "ignore") return;
+
+  event.preventDefault();
+  if (unavailable.value) {
+    event.stopImmediatePropagation();
+    return;
+  }
+  if (keyboardAction === "activate" && event.currentTarget instanceof HTMLElement) {
+    event.currentTarget.click();
+  }
+}
+
+function onKeydown(event: KeyboardEvent): void {
+  onKeyboard(event, "keydown");
+}
+
+function onKeyup(event: KeyboardEvent): void {
+  onKeyboard(event, "keyup");
+}
+
+function getShareButtonKeyboardAction(
+  key: string,
+  phase: ShareButtonKeyboardPhase,
+): ShareButtonKeyboardAction {
+  if (key === "Enter") return phase === "keydown" ? "activate" : "ignore";
+  if (key === " ") return phase === "keydown" ? "prevent" : "activate";
+  return "ignore";
+}
+
+function focus(options?: FocusOptions): void {
+  focusTarget(element.value, options);
+}
+
+function focusTarget(targetElement: unknown, options?: FocusOptions): void {
+  if (
+    typeof targetElement === "object" &&
+    targetElement !== null &&
+    "focus" in targetElement &&
+    typeof targetElement.focus === "function"
+  ) {
+    targetElement.focus(options);
+  }
+}
+
+function normalizeSharePayload(source: ShareButtonPayloadSource): ShareButtonPayload {
+  const payload: MutableShareButtonPayload = {};
+  if (source.title !== undefined) payload.title = source.title;
+  if (source.text !== undefined) payload.text = source.text;
+  if (source.url !== undefined) payload.url = source.url;
+  if (source.files !== undefined) payload.files = [...source.files];
+  return payload;
+}
+
+async function shareWithNavigator(payload: ShareButtonPayload): Promise<void> {
+  const platformNavigator = globalThis.navigator as PlatformNavigatorWithShare | undefined;
+  const share = platformNavigator?.share;
+  if (typeof share !== "function") throw new Error(SHARE_BUTTON_ACTION_UNAVAILABLE);
+  await share.call(platformNavigator, payload);
+}
+
+function hasText(nextValue: string | undefined): boolean {
+  return nextValue != null && nextValue.trim().length > 0;
+}
+
+type ShareButtonSetupExpose = Omit<
+  ShareButtonExpose,
+  "disabled" | "element" | "label" | "payload" | "sharing" | "state" | "unavailable"
+> & {
+  readonly disabled: ComputedRef<boolean>;
+  readonly element: typeof element;
+  readonly label: ComputedRef<string>;
+  readonly payload: ComputedRef<ShareButtonPayload>;
+  readonly sharing: ComputedRef<boolean>;
+  readonly state: Readonly<ShallowRef<ShareButtonState>>;
+  readonly unavailable: ComputedRef<boolean>;
+};
+
+const exposed = {
+  disabled: disabledValue,
+  element,
+  focus,
+  label,
+  payload: payloadValue,
+  sharing: sharingValue,
+  state: stateValue,
+  unavailable,
+} satisfies ShareButtonSetupExpose;
+
+defineExpose(exposed);
+</script>
+
+<template>
+  <component
+    :is="as"
+    ref="element"
+    :type="isNativeButton ? buttonType : undefined"
+    :disabled="isNativeButton ? disabledValue : undefined"
+    :role="isNativeButton ? undefined : 'button'"
+    :tabindex="tabIndex"
+    :aria-label="ariaLabelledbyValue === undefined ? ariaLabelValue : undefined"
+    :aria-labelledby="ariaLabelledbyValue"
+    :aria-describedby="ariaDescribedby"
+    :aria-disabled="unavailable && (!isNativeButton || sharingValue) ? 'true' : undefined"
+    :aria-busy="sharingValue ? 'true' : undefined"
+    data-vize-ui="share-button"
+    part="root"
+    :data-state="stateValue"
+    :data-disabled="disabledValue ? 'true' : undefined"
+    :data-sharing="sharingValue ? 'true' : undefined"
+    @click="onClick"
+    @keydown="onKeydown"
+    @keyup="onKeyup"
+  >
+    <slot v-bind="slotState">
+      <span data-vize-ui="share-button-label" part="label">{{ label }}</span>
+    </slot>
+  </component>
+</template>
+
+<style scoped>
+/* Headless by design. Native CSS remains entirely consumer-owned. */
+</style>

package/registry/files/families/actions/toolbar/examples/toolbar-basic.vue

@@ -0,0 +1,19 @@
+<!-- Labelled editor toolbar with roving focus that reports which action was pressed. -->
+<script setup lang="ts">
+import { ref } from "vue";
+
+import { Toolbar, ToolbarItem } from "../toolbar.ts";
+
+const lastAction = ref("none");
+</script>
+
+<template>
+  <div>
+    <Toolbar aria-label="Document actions" @press="(value) => (lastAction = value)">
+      <ToolbarItem value="save">Save</ToolbarItem>
+      <ToolbarItem value="duplicate">Duplicate</ToolbarItem>
+      <ToolbarItem value="publish" disabled>Publish</ToolbarItem>
+    </Toolbar>
+    <output>Last action: {{ lastAction }}</output>
+  </div>
+</template>

package/registry/files/families/actions/toolbar/toolbar-context.ts

@@ -0,0 +1,42 @@
+import type { ComputedRef, ShallowRef } from "vue";
+
+import { createContext } from "../../foundations/context/context.ts";
+import type { PrimitiveElement } from "../../foundations/primitive/primitive.ts";
+import type {
+  ToolbarDirection,
+  ToolbarItemState,
+  ToolbarOrientation,
+  ToolbarState,
+} from "./toolbar-types.ts";
+
+/** Registered item used by the root for DOM-order roving focus. */
+export interface ToolbarItemRegistration {
+  readonly value: () => string;
+  readonly disabled: ComputedRef<boolean>;
+  readonly element: Readonly<ShallowRef<PrimitiveElement | null>>;
+}
+
+/** Keyboard navigation request made by a Toolbar item. */
+export type ToolbarNavigationIntent = "first" | "last" | "next" | "previous";
+
+/** Shared state and actions for Toolbar compound items. */
+export interface ToolbarContextValue {
+  readonly activeValue: Readonly<ShallowRef<string | null>>;
+  readonly dir: ComputedRef<ToolbarDirection>;
+  readonly disabled: ComputedRef<boolean>;
+  readonly orientation: ComputedRef<ToolbarOrientation>;
+  readonly rovingFocus: ComputedRef<boolean>;
+  readonly state: ComputedRef<ToolbarState>;
+  readonly getItemState: (disabled: boolean) => ToolbarItemState;
+  readonly moveFocus: (
+    fromValue: string,
+    intent: ToolbarNavigationIntent,
+    options?: FocusOptions,
+  ) => boolean;
+  readonly registerItem: (item: ToolbarItemRegistration) => () => void;
+  readonly requestItemPress: (value: string, nativeEvent: MouseEvent) => void;
+  readonly setActiveValue: (value: string) => void;
+  readonly syncActiveValue: (item?: ToolbarItemRegistration) => void;
+}
+
+export const toolbarContext = createContext<ToolbarContextValue>("Toolbar");

package/registry/files/families/actions/toolbar/toolbar-contracts.ts

@@ -0,0 +1,38 @@
+import type { PrimitiveElement } from "../../foundations/primitive/primitive.ts";
+import type { ToolbarItemSlotState, ToolbarSlotState } from "./toolbar-types.ts";
+
+/** Slots exposed by the root Toolbar component. */
+export interface ToolbarSlots {
+  /** Renders grouped action controls with toolbar navigation state. */
+  default(props: ToolbarSlotState): unknown;
+}
+
+/** Slots exposed by ToolbarItem. */
+export interface ToolbarItemSlots {
+  /** Renders item contents with current availability and navigation state. */
+  default(props: ToolbarItemSlotState): unknown;
+}
+
+/** Public component instance state exposed by the root Toolbar component. */
+export interface ToolbarExpose extends ToolbarSlotState {
+  /** Currently active item value, or `null` before an item is focusable. */
+  readonly activeValue: string | null;
+
+  /** Rendered root element or component instance. */
+  readonly element: PrimitiveElement | null;
+
+  /** Move focus to the active or first enabled item. */
+  readonly focus: (options?: FocusOptions) => void;
+
+  /** Move focus to an enabled item by value and report whether it was found. */
+  readonly focusValue: (value: string, options?: FocusOptions) => boolean;
+}
+
+/** Public component instance state exposed by ToolbarItem. */
+export interface ToolbarItemExpose extends ToolbarItemSlotState {
+  /** Rendered item element or component instance. */
+  readonly element: PrimitiveElement | null;
+
+  /** Move focus to the rendered item. */
+  readonly focus: (options?: FocusOptions) => void;
+}

package/registry/files/families/actions/toolbar/toolbar-item.vue

@@ -0,0 +1,198 @@
+<script setup lang="ts">
+import { computed, onUnmounted, useTemplateRef, watch } from "vue";
+import type { ComputedRef } from "vue";
+
+import type { PrimitiveElement } from "../../foundations/primitive/primitive.ts";
+import type { ToolbarItemExpose } from "./toolbar-contracts.ts";
+import { toolbarContext } from "./toolbar-context.ts";
+import type { ToolbarNavigationIntent } from "./toolbar-context.ts";
+import type {
+  ToolbarItemEmits,
+  ToolbarItemProps,
+  ToolbarItemSlotState,
+  ToolbarItemState,
+} from "./toolbar-types.ts";
+
+type ToolbarKeyboardPhase = "keydown" | "keyup";
+type ToolbarKeyboardAction = "activate" | "prevent" | "ignore";
+
+function getToolbarKeyboardAction(key: string, phase: ToolbarKeyboardPhase): ToolbarKeyboardAction {
+  if (key === "Enter") return phase === "keydown" ? "activate" : "ignore";
+  if (key === " ") return phase === "keydown" ? "prevent" : "activate";
+  return "ignore";
+}
+
+const {
+  as = "button",
+  native = undefined,
+  type = "button",
+  value,
+  disabled = false,
+  ariaLabel = undefined,
+  ariaLabelledby = undefined,
+  ariaDescribedby = undefined,
+} = defineProps<ToolbarItemProps>();
+
+defineSlots<{
+  /** Renders item contents with current availability and navigation state. */
+  default(props: ToolbarItemSlotState): unknown;
+}>();
+
+const emit = defineEmits<ToolbarItemEmits>();
+
+const context = toolbarContext.use();
+const element = useTemplateRef<PrimitiveElement>("element");
+const isNativeButton = computed(() => native ?? as === "button");
+const itemDisabled = computed(() => context.disabled.value || disabled);
+const itemState = computed<ToolbarItemState>(() => context.getItemState(itemDisabled.value));
+const tabIndex = computed(() => {
+  if (itemDisabled.value) return isNativeButton.value ? undefined : -1;
+  if (!context.rovingFocus.value) return isNativeButton.value ? undefined : 0;
+  return context.activeValue.value === value ? 0 : -1;
+});
+const slotState = computed<ToolbarItemSlotState>(() => ({
+  dir: context.dir.value,
+  disabled: itemDisabled.value,
+  orientation: context.orientation.value,
+  state: itemState.value,
+  value,
+}));
+
+const registration = {
+  disabled: itemDisabled,
+  element,
+  value: () => value,
+};
+const unregister = context.registerItem(registration);
+
+watch([itemDisabled, () => value], () => context.syncActiveValue(registration), { flush: "sync" });
+onUnmounted(unregister);
+
+function onClick(event: MouseEvent): void {
+  if (itemDisabled.value) {
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    return;
+  }
+  context.requestItemPress(value, event);
+  emit("press", value, event);
+}
+
+function onFocus(): void {
+  if (!itemDisabled.value) context.setActiveValue(value);
+}
+
+function getNavigationIntent(key: string): ToolbarNavigationIntent | null {
+  if (key === "Home") return "first";
+  if (key === "End") return "last";
+  if (context.orientation.value === "horizontal") {
+    const nextKey = context.dir.value === "rtl" ? "ArrowLeft" : "ArrowRight";
+    const previousKey = context.dir.value === "rtl" ? "ArrowRight" : "ArrowLeft";
+    if (key === nextKey) return "next";
+    if (key === previousKey) return "previous";
+  } else {
+    if (key === "ArrowDown") return "next";
+    if (key === "ArrowUp") return "previous";
+  }
+  return null;
+}
+
+function onKeyboard(event: KeyboardEvent, phase: ToolbarKeyboardPhase): void {
+  if (phase === "keydown") {
+    const intent = getNavigationIntent(event.key);
+    if (intent !== null && context.moveFocus(value, intent)) {
+      event.preventDefault();
+      return;
+    }
+  }
+
+  if (isNativeButton.value) return;
+  const action = getToolbarKeyboardAction(event.key, phase);
+  if (action === "ignore") return;
+  event.preventDefault();
+  if (itemDisabled.value) {
+    event.stopImmediatePropagation();
+    return;
+  }
+  if (action === "activate" && event.currentTarget instanceof HTMLElement) {
+    event.currentTarget.click();
+  }
+}
+
+function onKeydown(event: KeyboardEvent): void {
+  onKeyboard(event, "keydown");
+}
+
+function onKeyup(event: KeyboardEvent): void {
+  onKeyboard(event, "keyup");
+}
+
+function focusTarget(target: unknown, options?: FocusOptions): void {
+  if (
+    typeof target === "object" &&
+    target !== null &&
+    "focus" in target &&
+    typeof target.focus === "function"
+  ) {
+    target.focus(options);
+  }
+}
+
+function focus(options?: FocusOptions): void {
+  focusTarget(element.value, options);
+}
+
+type ToolbarItemSetupExpose = Omit<
+  ToolbarItemExpose,
+  "dir" | "disabled" | "element" | "orientation" | "state"
+> & {
+  readonly dir: ComputedRef<ToolbarItemSlotState["dir"]>;
+  readonly disabled: ComputedRef<boolean>;
+  readonly element: typeof element;
+  readonly orientation: ComputedRef<ToolbarItemSlotState["orientation"]>;
+  readonly state: ComputedRef<ToolbarItemState>;
+};
+
+const exposed = {
+  dir: computed(() => context.dir.value),
+  disabled: itemDisabled,
+  element,
+  focus,
+  orientation: computed(() => context.orientation.value),
+  state: itemState,
+  value,
+} satisfies ToolbarItemSetupExpose;
+
+defineExpose(exposed);
+</script>
+
+<template>
+  <component
+    :is="as"
+    ref="element"
+    :type="isNativeButton ? type : undefined"
+    :disabled="isNativeButton ? itemDisabled : undefined"
+    :role="isNativeButton ? undefined : 'button'"
+    :tabindex="tabIndex"
+    :aria-label="ariaLabel"
+    :aria-labelledby="ariaLabelledby"
+    :aria-describedby="ariaDescribedby"
+    :aria-disabled="itemDisabled && !isNativeButton ? 'true' : undefined"
+    data-vize-ui="toolbar-item"
+    part="item"
+    :data-state="itemState"
+    :data-disabled="itemDisabled ? 'true' : undefined"
+    :data-orientation="context.orientation.value"
+    :data-value="value"
+    @click="onClick"
+    @focus="onFocus"
+    @keydown="onKeydown"
+    @keyup="onKeyup"
+  >
+    <slot v-bind="slotState" />
+  </component>
+</template>
+
+<style scoped>
+/* Headless by design. Native CSS remains entirely consumer-owned. */
+</style>