@limonify/zest-ui 0.1.0

package/src/menu/trigger/MenuTrigger.tsx

@@ -0,0 +1,142 @@
+'use client';
+import * as React from 'react';
+import { Pressable, type GestureResponderEvent } from 'react-native';
+import { MenuRootContext } from '../root/MenuRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import { useId } from '../../hooks/useId';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import { usePopupHandleStore } from '../../utils/popups/usePopupHandleStore';
+import type { MenuHandle } from '../store/MenuHandle';
+import type { MenuStore } from '../store/MenuStore';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A button that opens the menu, and the element it is positioned against.
+ * Renders a `<Pressable>`.
+ */
+export function MenuTrigger<Payload = unknown>(componentProps: MenuTrigger.Props<Payload>) {
+  const {
+    render,
+    className,
+    style,
+    disabled = false,
+    handle,
+    nativeID: idProp,
+    payload,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const rootStore = React.useContext(MenuRootContext);
+  const handleStore = usePopupHandleStore(handle);
+
+  // A trigger inside a root uses that root; a detached one follows its handle,
+  // which resolves to the attached root's store or to an inert fallback.
+  const store = (handleStore ?? rootStore) as MenuStore | undefined;
+
+  if (store === undefined) {
+    throw new Error(
+      'Zest: Menu.Trigger must be placed within <Menu.Root>, or given a `handle` it shares with one.',
+    );
+  }
+
+  const id = useId(idProp ?? undefined);
+  const open = store.useState('open');
+
+  const [pressed, setPressed] = React.useState(false);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const anchorRef = React.useCallback(
+    (node: unknown) => {
+      store.set('triggerNode', node);
+    },
+    [store],
+  );
+  const mergedRef = useMergedRefs(ref, anchorRef);
+
+  // Registering into whichever store is current is what lets a handle resolve
+  // `open(id)`. The effect re-runs when the handle swaps stores, migrating the
+  // registration to the root that just attached.
+  useIsoLayoutEffect(() => {
+    if (id === undefined) {
+      return undefined;
+    }
+
+    store.context.triggerNodes.add(id, store.state.triggerNode);
+
+    return () => {
+      store.context.triggerNodes.delete(id);
+    };
+  }, [store, id]);
+
+  const state: MenuTriggerState = { disabled, open, pressed };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref: mergedRef,
+    props: [
+      {
+        nativeID: id,
+        onPress(event: GestureResponderEvent) {
+          if (payload !== undefined) {
+            store.set('payload', payload);
+          }
+          if (id !== undefined) {
+            store.set('triggerId', id);
+          }
+
+          store.setOpen(!open, createChangeEventDetails(REASONS.triggerPress, event));
+        },
+        onPressIn() {
+          setPressed(true);
+        },
+        onPressOut() {
+          setPressed(false);
+        },
+        onLayout() {
+          store.state.update?.();
+        },
+        accessibilityState: { expanded: open, disabled: disabled || undefined },
+        'aria-haspopup': 'menu' as const,
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+}
+
+export interface MenuTriggerState {
+  disabled: boolean;
+  open: boolean;
+  pressed: boolean;
+}
+
+export interface MenuTriggerProps<Payload = unknown>
+  extends ZestUIComponentProps<typeof Pressable, MenuTriggerState> {
+  /**
+   * A handle shared with a `Menu.Root`, which is what lets this trigger live
+   * outside of it. Create one with `Menu.createHandle()`.
+   *
+   * The trigger's `nativeID` is the id a handle's `open(triggerId)` resolves.
+   */
+  handle?: MenuHandle<Payload> | undefined;
+  /**
+   * A payload handed to the root's children when they are a function.
+   */
+  payload?: Payload | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+}
+
+export namespace MenuTrigger {
+  export type State = MenuTriggerState;
+  export type Props<Payload = unknown> = MenuTriggerProps<Payload>;
+}

package/src/merge-props/index.ts

@@ -0,0 +1,7 @@
+export {
+  mergeProps,
+  mergePropsN,
+  mergeClassNames,
+  mergeStyles,
+  makeEventPreventable,
+} from './mergeProps';

package/src/merge-props/mergeProps.ts

@@ -0,0 +1,288 @@
+import type * as React from 'react';
+import type { ZestUIEvent, NativeProps, WithZestUIEvent } from '../types';
+
+type ElementType = React.ElementType;
+type PropsOf<T extends React.ElementType> = WithZestUIEvent<React.ComponentPropsWithRef<T>>;
+type InputProps<T extends React.ElementType> =
+  | PropsOf<T>
+  | ((otherProps: PropsOf<T>) => PropsOf<T>)
+  | undefined;
+
+const EMPTY_PROPS = {};
+
+/* eslint-disable id-denylist */
+/**
+ * Merges multiple sets of React props. It follows the Object.assign pattern where the rightmost object's fields overwrite
+ * the conflicting ones from others. This doesn't apply to event handlers, `className` and `style` props.
+ *
+ * Event handlers are merged and called in right-to-left order (rightmost handler executes first, leftmost last).
+ * For React synthetic events, the rightmost handler can prevent prior (left-positioned) handlers from executing
+ * by calling `event.preventZestUIHandler()`.
+ *
+ * The `className` prop is merged by concatenating classes in right-to-left order (rightmost class appears first in the string).
+ * The `style` prop is merged by composing a React Native style array `[left, right]`, so the rightmost styles win
+ * when React Native flattens the array.
+ *
+ * Props can either be provided as objects or as functions that take the previous props as an argument.
+ *
+ * @important **`ref` is not merged.**
+ * @public
+ */
+export function mergeProps<T extends ElementType>(
+  a: InputProps<T>,
+  b: InputProps<T>,
+  c: InputProps<T>,
+  d: InputProps<T>,
+  e: InputProps<T>,
+): PropsOf<T>;
+export function mergeProps<T extends ElementType>(
+  a: InputProps<T>,
+  b: InputProps<T>,
+  c: InputProps<T>,
+  d: InputProps<T>,
+): PropsOf<T>;
+export function mergeProps<T extends ElementType>(
+  a: InputProps<T>,
+  b: InputProps<T>,
+  c: InputProps<T>,
+): PropsOf<T>;
+export function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>): PropsOf<T>;
+export function mergeProps(a: any, b: any, c?: any, d?: any, e?: any) {
+  if (!c && !d && !e && !a) {
+    return createInitialMergedProps(b);
+  }
+
+  // We need to mutably own `merged`.
+  let merged = createInitialMergedProps(a);
+
+  if (b) {
+    merged = mergeInto(merged, b);
+  }
+  if (c) {
+    merged = mergeInto(merged, c);
+  }
+  if (d) {
+    merged = mergeInto(merged, d);
+  }
+  if (e) {
+    merged = mergeInto(merged, e);
+  }
+
+  return merged;
+}
+/* eslint-enable id-denylist */
+
+/**
+ * Merges an arbitrary number of React props using the same logic as {@link mergeProps}.
+ * This function accepts an array of props instead of individual arguments.
+ *
+ * @param props Array of props to merge.
+ * @returns The merged props.
+ * @see mergeProps
+ * @public
+ */
+export function mergePropsN<T extends ElementType>(props: InputProps<T>[]): PropsOf<T> {
+  if (props.length === 0) {
+    return EMPTY_PROPS as PropsOf<T>;
+  }
+  if (props.length === 1) {
+    return createInitialMergedProps(props[0]) as PropsOf<T>;
+  }
+
+  // We need to mutably own `merged`.
+  let merged = createInitialMergedProps(props[0]);
+
+  for (let i = 1; i < props.length; i += 1) {
+    merged = mergeInto(merged, props[i]);
+  }
+
+  return merged as PropsOf<T>;
+}
+
+function createInitialMergedProps<T extends ElementType>(inputProps: InputProps<T>) {
+  if (isPropsGetter(inputProps)) {
+    // Getter-returned handlers intentionally keep their existing semantics.
+    return { ...resolvePropsGetter(inputProps, EMPTY_PROPS) };
+  }
+
+  return copyInitialProps(inputProps);
+}
+
+function mergeInto<T extends ElementType>(merged: Record<string, any>, inputProps: InputProps<T>) {
+  if (isPropsGetter(inputProps)) {
+    return resolvePropsGetter(inputProps, merged as PropsOf<T>);
+  }
+  return mutablyMergeInto(merged, inputProps);
+}
+
+function copyInitialProps(inputProps: NativeProps | undefined) {
+  const copiedProps = { ...inputProps } as Record<string, any>;
+
+  // eslint-disable-next-line guard-for-in
+  for (const propName in copiedProps) {
+    const propValue = copiedProps[propName];
+    if (isEventHandler(propName, propValue)) {
+      copiedProps[propName] = wrapEventHandler(propValue);
+    }
+  }
+
+  return copiedProps;
+}
+
+/**
+ * Merges two sets of props. In case of conflicts, the external props take precedence.
+ */
+function mutablyMergeInto(
+  mergedProps: Record<string, any>,
+  externalProps: NativeProps | undefined,
+) {
+  if (!externalProps) {
+    return mergedProps;
+  }
+
+  // eslint-disable-next-line guard-for-in
+  for (const propName in externalProps) {
+    const externalPropValue = externalProps[propName];
+
+    switch (propName) {
+      case 'style': {
+        mergedProps[propName] = mergeStyles(mergedProps.style, externalPropValue);
+        break;
+      }
+      case 'className': {
+        mergedProps[propName] = mergeClassNames(mergedProps.className, externalPropValue as string);
+        break;
+      }
+      default: {
+        if (isEventHandler(propName, externalPropValue)) {
+          mergedProps[propName] = mergeEventHandlers(mergedProps[propName], externalPropValue);
+        } else {
+          mergedProps[propName] = externalPropValue;
+        }
+      }
+    }
+  }
+
+  return mergedProps;
+}
+
+function isEventHandler(key: string, value: unknown) {
+  // This approach is more efficient than using a regex.
+  const code0 = key.charCodeAt(0);
+  const code1 = key.charCodeAt(1);
+  const code2 = key.charCodeAt(2);
+  return (
+    code0 === 111 /* o */ &&
+    code1 === 110 /* n */ &&
+    code2 >= 65 /* A */ &&
+    code2 <= 90 /* Z */ &&
+    (typeof value === 'function' || typeof value === 'undefined')
+  );
+}
+
+function isPropsGetter<T extends React.ElementType>(
+  inputProps: InputProps<T>,
+): inputProps is (props: PropsOf<T>) => PropsOf<T> {
+  return typeof inputProps === 'function';
+}
+
+function resolvePropsGetter<T extends ElementType>(
+  inputProps: InputProps<ElementType>,
+  previousProps: PropsOf<T>,
+) {
+  if (isPropsGetter(inputProps)) {
+    return inputProps(previousProps);
+  }
+
+  return inputProps ?? (EMPTY_PROPS as PropsOf<T>);
+}
+
+function mergeEventHandlers(ourHandler: Function | undefined, theirHandler: Function | undefined) {
+  if (!theirHandler) {
+    return ourHandler;
+  }
+  if (!ourHandler) {
+    return wrapEventHandler(theirHandler);
+  }
+
+  return (...args: unknown[]) => {
+    const event = args[0];
+
+    if (isSyntheticEvent(event)) {
+      const baseUIEvent = event as ZestUIEvent<typeof event>;
+
+      makeEventPreventable(baseUIEvent);
+
+      const result = theirHandler(...args);
+
+      if (!baseUIEvent.baseUIHandlerPrevented) {
+        ourHandler?.(...args);
+      }
+
+      return result;
+    }
+
+    const result = theirHandler(...args);
+    ourHandler?.(...args);
+    return result;
+  };
+}
+
+function wrapEventHandler(handler: Function | undefined) {
+  if (!handler) {
+    return handler;
+  }
+
+  return (...args: unknown[]) => {
+    const event = args[0];
+
+    if (isSyntheticEvent(event)) {
+      makeEventPreventable(event as ZestUIEvent<typeof event>);
+    }
+
+    return handler(...args);
+  };
+}
+
+export function makeEventPreventable<T extends object>(event: ZestUIEvent<T>) {
+  event.preventZestUIHandler = () => {
+    (event.baseUIHandlerPrevented as boolean) = true;
+  };
+
+  return event;
+}
+
+/**
+ * Composes two React Native styles into an array so the rightmost style wins
+ * when flattened. Never object-spreads: styles may be registered StyleSheet
+ * IDs or nested arrays.
+ */
+export function mergeStyles(ourStyle: unknown, theirStyle: unknown) {
+  if (ourStyle == null) {
+    return theirStyle;
+  }
+  if (theirStyle == null) {
+    return ourStyle;
+  }
+  return [ourStyle, theirStyle];
+}
+
+export function mergeClassNames(
+  ourClassName: string | undefined,
+  theirClassName: string | undefined,
+) {
+  if (theirClassName) {
+    if (ourClassName) {
+      // eslint-disable-next-line prefer-template
+      return theirClassName + ' ' + ourClassName;
+    }
+
+    return theirClassName;
+  }
+
+  return ourClassName;
+}
+
+function isSyntheticEvent(event: unknown): event is React.SyntheticEvent {
+  return event != null && typeof event === 'object' && 'nativeEvent' in event;
+}

package/src/meter/index.parts.ts

@@ -0,0 +1,5 @@
+export { MeterRoot as Root } from './root/MeterRoot';
+export { MeterTrack as Track } from './track/MeterTrack';
+export { MeterIndicator as Indicator } from './indicator/MeterIndicator';
+export { MeterLabel as Label } from './label/MeterLabel';
+export { MeterValue as Value } from './value/MeterValue';

package/src/meter/index.ts

@@ -0,0 +1,8 @@
+export * as Meter from './index.parts';
+
+export type * from './root/MeterRoot';
+export type * from './track/MeterTrack';
+export type * from './indicator/MeterIndicator';
+export type * from './label/MeterLabel';
+export type * from './value/MeterValue';
+export { useMeterRootContext } from './root/MeterRootContext';

package/src/meter/indicator/MeterIndicator.tsx

@@ -0,0 +1,33 @@
+'use client';
+import { View } from 'react-native';
+import { useMeterRootContext } from '../root/MeterRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * Visualizes the current value.
+ * Renders a `<View>` sized to the value's position in the range.
+ */
+export function MeterIndicator(componentProps: MeterIndicator.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const { percentageValue } = useMeterRootContext();
+
+  const state: MeterIndicatorState = {};
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [{ style: { width: `${percentageValue}%` as const } }, elementProps],
+  });
+}
+
+export interface MeterIndicatorState {}
+
+export interface MeterIndicatorProps
+  extends ZestUIComponentProps<typeof View, MeterIndicatorState> {}
+
+export namespace MeterIndicator {
+  export type State = MeterIndicatorState;
+  export type Props = MeterIndicatorProps;
+}

package/src/meter/label/MeterLabel.tsx

@@ -0,0 +1,41 @@
+'use client';
+import { Text } from 'react-native';
+import { useMeterRootContext } from '../root/MeterRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useId } from '../../hooks/useId';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * An accessible label for the meter.
+ * Renders a `<Text>`.
+ */
+export function MeterLabel(componentProps: MeterLabel.Props) {
+  const { render, className, style, nativeID: idProp, ref, ...elementProps } = componentProps;
+
+  const { setLabelId } = useMeterRootContext();
+
+  const id = useId(idProp ?? undefined);
+
+  useIsoLayoutEffect(() => {
+    setLabelId(id);
+    return () => setLabelId(undefined);
+  }, [id, setLabelId]);
+
+  const state: MeterLabelState = {};
+
+  return useRenderElement(Text, componentProps, {
+    state,
+    ref,
+    props: [{ nativeID: id }, elementProps],
+  });
+}
+
+export interface MeterLabelState {}
+
+export interface MeterLabelProps extends ZestUIComponentProps<typeof Text, MeterLabelState> {}
+
+export namespace MeterLabel {
+  export type State = MeterLabelState;
+  export type Props = MeterLabelProps;
+}

package/src/meter/root/MeterRoot.tsx

@@ -0,0 +1,122 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { clamp } from '../../utils/clamp';
+import { formatNumber } from '../../utils/formatNumber';
+import type { ZestUIComponentProps } from '../../types';
+import { MeterRootContext } from './MeterRootContext';
+
+/**
+ * Groups all parts of the meter and announces the value to screen readers.
+ * Renders a `<View>`.
+ *
+ * A meter is a static gauge (disk usage, battery level), unlike `Progress`
+ * which tracks a task towards completion — so it has no indeterminate state and
+ * no `status`. Everything else mirrors `Progress`.
+ *
+ * **Not ported from upstream.** The visually-hidden `<span>` holding an `x`
+ * (an NVDA workaround, a Windows screen reader).
+ */
+export function MeterRoot(componentProps: MeterRoot.Props) {
+  const {
+    className,
+    format,
+    getAccessibilityValueText,
+    locale,
+    max = 100,
+    min = 0,
+    render,
+    style,
+    value,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const [labelId, setLabelId] = React.useState<string | undefined>(undefined);
+
+  const rawPercentage = valueToPercent(value, min, max);
+  const percentageValue = clamp(Number.isNaN(rawPercentage) ? 0 : rawPercentage, 0, 100);
+  const clampedValue = clamp(Number.isNaN(value) ? min : value, min, max);
+
+  // Without an explicit `format` the value reads as its position in the range,
+  // so the text stays in sync with the indicator fill for any min/max.
+  const formattedValue = format
+    ? formatNumber(value, locale, format)
+    : formatNumber(percentageValue / 100, locale, { style: 'percent' });
+
+  const state: MeterRootState = React.useMemo(() => ({}), []);
+
+  const contextValue: MeterRootContext = React.useMemo(
+    () => ({ formattedValue, percentageValue, setLabelId, value }),
+    [formattedValue, percentageValue, value],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        // React Native's `accessibilityRole` has no 'meter'; the W3C `role`
+        // prop does, and 'progressbar' is the closest native fallback.
+        role: 'meter' as const,
+        accessibilityRole: 'progressbar' as const,
+        accessibilityLabelledBy: labelId,
+        accessibilityValue: {
+          min,
+          max,
+          now: clampedValue,
+          text: getAccessibilityValueText
+            ? getAccessibilityValueText(formattedValue, value)
+            : formattedValue,
+        },
+        'aria-labelledby': labelId,
+      },
+      elementProps,
+    ],
+  });
+
+  return <MeterRootContext.Provider value={contextValue}>{element}</MeterRootContext.Provider>;
+}
+
+function valueToPercent(value: number, min: number, max: number) {
+  return ((value - min) * 100) / (max - min);
+}
+
+export interface MeterRootState {}
+
+export interface MeterRootProps extends ZestUIComponentProps<typeof View, MeterRootState> {
+  /**
+   * The current value.
+   */
+  value: number;
+  /**
+   * The minimum value.
+   * @default 0
+   */
+  min?: number | undefined;
+  /**
+   * The maximum value.
+   * @default 100
+   */
+  max?: number | undefined;
+  /**
+   * Options to format the value.
+   */
+  format?: Intl.NumberFormatOptions | undefined;
+  /**
+   * The locale used by `Intl.NumberFormat` when formatting the value.
+   * Defaults to the user's runtime locale.
+   */
+  locale?: Intl.LocalesArgument | undefined;
+  /**
+   * Returns a human-readable text alternative for the current value, announced
+   * by assistive technology.
+   */
+  getAccessibilityValueText?: ((formattedValue: string, value: number) => string) | undefined;
+}
+
+export namespace MeterRoot {
+  export type State = MeterRootState;
+  export type Props = MeterRootProps;
+}

package/src/meter/root/MeterRootContext.ts

@@ -0,0 +1,32 @@
+'use client';
+import * as React from 'react';
+
+export interface MeterRootContext {
+  /**
+   * The current value.
+   */
+  value: number;
+  /**
+   * The value formatted for display.
+   */
+  formattedValue: string;
+  /**
+   * The value's position in the range as a percentage. This is what the
+   * indicator is sized from.
+   */
+  percentageValue: number;
+  setLabelId: (id: string | undefined) => void;
+}
+
+export const MeterRootContext = React.createContext<MeterRootContext | undefined>(undefined);
+
+export function useMeterRootContext() {
+  const context = React.useContext(MeterRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: MeterRootContext is missing. Meter parts must be placed within <Meter.Root>.',
+    );
+  }
+
+  return context;
+}