@limonify/zest-ui 0.1.0

package/src/avatar/root/AvatarRoot.tsx

@@ -0,0 +1,48 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+import { AvatarRootContext } from './AvatarRootContext';
+
+/**
+ * Displays a user's profile picture, initials, or fallback icon.
+ * Renders a `<View>`.
+ */
+export function AvatarRoot(componentProps: AvatarRoot.Props) {
+  const { className, render, style, ref, ...elementProps } = componentProps;
+
+  const [imageLoadingStatus, setImageLoadingStatus] = React.useState<ImageLoadingStatus>('idle');
+
+  const state: AvatarRootState = { imageLoadingStatus };
+
+  const contextValue: AvatarRootContext = React.useMemo(
+    () => ({ imageLoadingStatus, setImageLoadingStatus }),
+    [imageLoadingStatus],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: elementProps,
+  });
+
+  return <AvatarRootContext.Provider value={contextValue}>{element}</AvatarRootContext.Provider>;
+}
+
+export type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+
+export interface AvatarRootState {
+  /**
+   * The image loading status.
+   */
+  imageLoadingStatus: ImageLoadingStatus;
+}
+
+export interface AvatarRootProps extends ZestUIComponentProps<typeof View, AvatarRootState> {}
+
+export namespace AvatarRoot {
+  export type State = AvatarRootState;
+  export type Props = AvatarRootProps;
+  export type LoadingStatus = ImageLoadingStatus;
+}

package/src/avatar/root/AvatarRootContext.ts

@@ -0,0 +1,21 @@
+'use client';
+import * as React from 'react';
+import type { ImageLoadingStatus } from './AvatarRoot';
+
+export interface AvatarRootContext {
+  imageLoadingStatus: ImageLoadingStatus;
+  setImageLoadingStatus: React.Dispatch<React.SetStateAction<ImageLoadingStatus>>;
+}
+
+export const AvatarRootContext = React.createContext<AvatarRootContext | undefined>(undefined);
+
+export function useAvatarRootContext() {
+  const context = React.useContext(AvatarRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: AvatarRootContext is missing. Avatar parts must be placed within <Avatar.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/button/Button.tsx

@@ -0,0 +1,64 @@
+'use client';
+import * as React from 'react';
+import { Pressable } from 'react-native';
+import { useButton } from '../internals/use-button/useButton';
+import { useRenderElement } from '../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../types';
+
+/**
+ * A button component that can be used to trigger actions.
+ * Renders a `<Pressable>`.
+ */
+export function Button(componentProps: Button.Props) {
+  const { render, className, disabled = false, style, ref, ...elementProps } = componentProps;
+
+  // The web version gets `:active` from CSS; React Native must track the
+  // pressed state explicitly so `style`/`className`/`render` functions can
+  // react to it.
+  const [pressed, setPressed] = React.useState(false);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const state: ButtonState = { disabled, pressed };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        onPressIn() {
+          setPressed(true);
+        },
+        onPressOut() {
+          setPressed(false);
+        },
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+}
+
+export interface ButtonState {
+  /**
+   * Whether the button should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the button is currently pressed.
+   */
+  pressed: boolean;
+}
+
+export interface ButtonProps extends ZestUIComponentProps<typeof Pressable, ButtonState> {
+  /**
+   * Whether the button should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+}
+
+export namespace Button {
+  export type State = ButtonState;
+  export type Props = ButtonProps;
+}

package/src/button/index.ts

@@ -0,0 +1,3 @@
+export { Button } from './Button';
+
+export type * from './Button';

package/src/checkbox/index.parts.ts

@@ -0,0 +1,2 @@
+export { CheckboxRoot as Root } from './root/CheckboxRoot';
+export { CheckboxIndicator as Indicator } from './indicator/CheckboxIndicator';

package/src/checkbox/index.ts

@@ -0,0 +1,4 @@
+export * as Checkbox from './index.parts';
+
+export type * from './root/CheckboxRoot';
+export type * from './indicator/CheckboxIndicator';

package/src/checkbox/indicator/CheckboxIndicator.tsx

@@ -0,0 +1,69 @@
+'use client';
+import { View } from 'react-native';
+import { useCheckboxRootContext } from '../root/CheckboxRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useTransitionStatus, type TransitionStatus } from '../../internals/useTransitionStatus';
+import type { CheckboxRootState } from '../root/CheckboxRoot';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * Indicates whether the checkbox is ticked.
+ * Renders a `<View>`, or nothing when the checkbox is unchecked.
+ *
+ * Follows the animation contract: with `keepMounted`, the indicator stays
+ * mounted while unchecked and publishes `transitionStatus` so the consumer can
+ * animate it out. Without it, the indicator unmounts the moment it unchecks —
+ * React Native cannot report when an exit animation finished.
+ */
+export function CheckboxIndicator(componentProps: CheckboxIndicator.Props) {
+  const { render, className, style, keepMounted = false, ref, ...elementProps } = componentProps;
+
+  const rootState = useCheckboxRootContext();
+
+  const rendered = rootState.checked || rootState.indeterminate;
+
+  const { mounted, transitionStatus, setMounted } = useTransitionStatus(rendered);
+
+  // Nothing reports when an exit animation finished, so an indicator that isn't
+  // kept mounted is unmounted the moment it unchecks.
+  useIsoLayoutEffect(() => {
+    if (!rendered && mounted && !keepMounted) {
+      setMounted(false);
+    }
+  }, [rendered, mounted, keepMounted, setMounted]);
+
+  const state: CheckboxIndicatorState = { ...rootState, transitionStatus };
+
+  const shouldRender = keepMounted || mounted;
+
+  return useRenderElement(View, componentProps, {
+    ref,
+    state,
+    enabled: shouldRender,
+    props: elementProps,
+  });
+}
+
+export interface CheckboxIndicatorState extends CheckboxRootState {
+  /**
+   * The transition status of the indicator, for driving enter/exit animations.
+   */
+  transitionStatus: TransitionStatus;
+}
+
+export interface CheckboxIndicatorProps
+  extends ZestUIComponentProps<typeof View, CheckboxIndicatorState> {
+  /**
+   * Whether to keep the element mounted when the checkbox is not checked.
+   *
+   * Required to animate the indicator out; without it, it unmounts on uncheck.
+   * @default false
+   */
+  keepMounted?: boolean | undefined;
+}
+
+export namespace CheckboxIndicator {
+  export type State = CheckboxIndicatorState;
+  export type Props = CheckboxIndicatorProps;
+}

package/src/checkbox/root/CheckboxRoot.tsx

@@ -0,0 +1,247 @@
+'use client';
+import * as React from 'react';
+import { Pressable, type GestureResponderEvent } from 'react-native';
+import { useControlled } from '../../hooks/useControlled';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import type { ZestUIComponentProps } from '../../types';
+import {
+  createChangeEventDetails,
+  type ZestChangeEventDetails,
+} from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import { useCheckboxGroupContext } from '../../checkbox-group/CheckboxGroupContext';
+import { useFieldControlRegistration } from '../../internals/field/useFieldControlRegistration';
+import { CheckboxRootContext } from './CheckboxRootContext';
+
+/**
+ * Represents the checkbox itself.
+ * Renders a `<Pressable>`.
+ *
+ * Placed inside a `Field.Root`, it is labelled by `Field.Label`, described by
+ * `Field.Description`/`Error`, inherits the field's `disabled`, and runs the
+ * field's `validate` on change.
+ */
+export function CheckboxRoot(componentProps: CheckboxRoot.Props) {
+  const {
+    checked: checkedProp,
+    className,
+    defaultChecked = false,
+    disabled: disabledProp = false,
+    indeterminate = false,
+    onCheckedChange,
+    parent = false,
+    readOnly = false,
+    render,
+    required = false,
+    style,
+    value,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const groupContext = useCheckboxGroupContext();
+  const parentContext = groupContext?.parent;
+  const isGroupedWithParent = parentContext != null && groupContext?.allValues != null;
+
+  const { fieldDisabled, fieldProps, validateField } = useFieldControlRegistration();
+
+  const disabled = (groupContext?.disabled || disabledProp || fieldDisabled) ?? false;
+
+  const { getButtonProps } = useButton({ disabled });
+
+  let groupProps: Partial<Pick<CheckboxRoot.Props, 'checked' | 'indeterminate' | 'onCheckedChange'>> =
+    {};
+  if (isGroupedWithParent) {
+    if (parent) {
+      groupProps = parentContext.getParentProps();
+    } else if (value) {
+      groupProps = parentContext.getChildProps(value);
+    }
+  }
+
+  const {
+    checked: groupChecked = checkedProp,
+    indeterminate: groupIndeterminate = indeterminate,
+    onCheckedChange: groupOnChange,
+  } = groupProps;
+
+  const groupValue = groupContext?.value;
+  const setGroupValue = groupContext?.setValue;
+  const defaultGroupValue = groupContext?.defaultValue;
+
+  const [checked, setCheckedState] = useControlled({
+    controlled: value && groupValue && !parent ? groupValue.includes(value) : groupChecked,
+    default:
+      value && defaultGroupValue && !parent ? defaultGroupValue.includes(value) : defaultChecked,
+    name: 'Checkbox',
+    state: 'checked',
+  });
+
+  const computedChecked = isGroupedWithParent ? Boolean(groupChecked) : checked;
+  const computedIndeterminate = isGroupedWithParent
+    ? groupIndeterminate || indeterminate
+    : indeterminate;
+
+  React.useEffect(() => {
+    if (!parentContext || !value) {
+      return undefined;
+    }
+
+    const disabledStates = parentContext.disabledStatesRef.current;
+    disabledStates.set(value, disabled);
+
+    return () => {
+      disabledStates.delete(value);
+    };
+  }, [parentContext, disabled, value]);
+
+  const state: CheckboxRootState = React.useMemo(
+    () => ({
+      checked: computedChecked,
+      disabled,
+      readOnly,
+      required,
+      indeterminate: computedIndeterminate,
+    }),
+    [computedChecked, disabled, readOnly, required, computedIndeterminate],
+  );
+
+  const element = useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        onPress(event: GestureResponderEvent) {
+          if (readOnly || disabled) {
+            return;
+          }
+
+          const nextChecked = !computedChecked;
+          const eventDetails = createChangeEventDetails(REASONS.none, event);
+
+          onCheckedChange?.(nextChecked, eventDetails);
+
+          if (eventDetails.isCanceled) {
+            return;
+          }
+
+          groupOnChange?.(nextChecked, eventDetails);
+
+          if (eventDetails.isCanceled) {
+            return;
+          }
+
+          setCheckedState(nextChecked);
+          validateField(nextChecked);
+
+          if (value && groupValue && setGroupValue && !parent && !isGroupedWithParent) {
+            const nextGroupValue = nextChecked
+              ? [...groupValue, value]
+              : groupValue.filter((item) => item !== value);
+
+            setGroupValue(nextGroupValue, eventDetails);
+          }
+        },
+        accessibilityRole: 'checkbox' as const,
+        accessibilityState: {
+          checked: computedIndeterminate ? ('mixed' as const) : computedChecked,
+          disabled: disabled || undefined,
+        },
+        ...fieldProps,
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+
+  return (
+    <CheckboxRootContext.Provider value={state}>{element}</CheckboxRootContext.Provider>
+  );
+}
+
+export interface CheckboxRootState {
+  /**
+   * Whether the checkbox is currently ticked.
+   */
+  checked: boolean;
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the user should be unable to tick or untick the checkbox.
+   */
+  readOnly: boolean;
+  /**
+   * Whether the user must tick the checkbox before submitting a form.
+   */
+  required: boolean;
+  /**
+   * Whether the checkbox is in a mixed state: neither ticked, nor unticked.
+   */
+  indeterminate: boolean;
+}
+
+export interface CheckboxRootProps
+  extends Omit<ZestUIComponentProps<typeof Pressable, CheckboxRootState>, 'onPress' | 'value'> {
+  /**
+   * Whether the checkbox is currently ticked.
+   *
+   * To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
+   */
+  checked?: boolean | undefined;
+  /**
+   * The value identifying the checkbox within a `<CheckboxGroup>`.
+   */
+  value?: string | undefined;
+  /**
+   * Whether the checkbox controls a parent checkbox in a `<CheckboxGroup>`.
+   * A parent checkbox ticks or unticks all of the group's checkboxes at once,
+   * and reports a mixed state while only some of them are ticked.
+   * @default false
+   */
+  parent?: boolean | undefined;
+  /**
+   * Whether the checkbox is initially ticked.
+   *
+   * To render a controlled checkbox, use the `checked` prop instead.
+   * @default false
+   */
+  defaultChecked?: boolean | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Whether the checkbox is in a mixed state: neither ticked, nor unticked.
+   * @default false
+   */
+  indeterminate?: boolean | undefined;
+  /**
+   * Event handler called when the checkbox is ticked or unticked.
+   */
+  onCheckedChange?:
+    | ((checked: boolean, eventDetails: CheckboxRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Whether the user should be unable to tick or untick the checkbox.
+   * @default false
+   */
+  readOnly?: boolean | undefined;
+  /**
+   * Whether the user must tick the checkbox before submitting a form.
+   * @default false
+   */
+  required?: boolean | undefined;
+}
+
+export type CheckboxRootChangeEventReason = typeof REASONS.none;
+
+export namespace CheckboxRoot {
+  export type State = CheckboxRootState;
+  export type Props = CheckboxRootProps;
+  export type ChangeEventReason = CheckboxRootChangeEventReason;
+  export type ChangeEventDetails = ZestChangeEventDetails<CheckboxRootChangeEventReason>;
+}

package/src/checkbox/root/CheckboxRootContext.ts

@@ -0,0 +1,18 @@
+'use client';
+import * as React from 'react';
+import type { CheckboxRootState } from './CheckboxRoot';
+
+export type CheckboxRootContext = CheckboxRootState;
+
+export const CheckboxRootContext = React.createContext<CheckboxRootContext | undefined>(undefined);
+
+export function useCheckboxRootContext() {
+  const context = React.useContext(CheckboxRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: CheckboxRootContext is missing. Checkbox parts must be placed within <Checkbox.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/checkbox-group/CheckboxGroup.tsx

@@ -0,0 +1,133 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useControlled } from '../hooks/useControlled';
+import { useStableCallback } from '../hooks/useStableCallback';
+import { useRenderElement } from '../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../types';
+import type { ZestChangeEventDetails } from '../utils/createChangeEventDetails';
+import { REASONS } from '../utils/reasons';
+import { CheckboxGroupContext } from './CheckboxGroupContext';
+import { useCheckboxGroupParent } from './useCheckboxGroupParent';
+
+const EMPTY_ARRAY: never[] = [];
+
+/**
+ * Provides a shared state to a series of checkboxes.
+ * Renders a `<View>`.
+ */
+export function CheckboxGroup(componentProps: CheckboxGroup.Props) {
+  const {
+    allValues,
+    className,
+    defaultValue: defaultValueProp,
+    disabled = false,
+    onValueChange,
+    render,
+    style,
+    value: valueProp,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const defaultValue =
+    valueProp === undefined ? (defaultValueProp ?? (EMPTY_ARRAY as string[])) : undefined;
+
+  const [value, setValueUnwrapped] = useControlled<string[]>({
+    controlled: valueProp,
+    default: defaultValue,
+    name: 'CheckboxGroup',
+    state: 'value',
+  });
+
+  const setValue = useStableCallback((v: string[], eventDetails: CheckboxGroup.ChangeEventDetails) => {
+    onValueChange?.(v, eventDetails);
+
+    if (eventDetails.isCanceled) {
+      return;
+    }
+
+    setValueUnwrapped(v);
+  });
+
+  const parent = useCheckboxGroupParent({ allValues, value, onValueChange: setValue });
+
+  const state: CheckboxGroupState = { disabled };
+
+  const contextValue: CheckboxGroupContext = React.useMemo(
+    () => ({
+      allValues,
+      value,
+      defaultValue,
+      setValue,
+      parent,
+      disabled,
+    }),
+    [allValues, value, defaultValue, setValue, parent, disabled],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        role: 'group' as const,
+        accessibilityState: { disabled: disabled || undefined },
+      },
+      elementProps,
+    ],
+  });
+
+  return <CheckboxGroupContext.Provider value={contextValue}>{element}</CheckboxGroupContext.Provider>;
+}
+
+export interface CheckboxGroupState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+}
+
+export interface CheckboxGroupProps
+  extends Omit<ZestUIComponentProps<typeof View, CheckboxGroupState>, 'value'> {
+  /**
+   * Names of the checkboxes in the group that should be ticked.
+   *
+   * To render an uncontrolled checkbox group, use the `defaultValue` prop instead.
+   */
+  value?: string[] | undefined;
+  /**
+   * Names of the checkboxes in the group that should be initially ticked.
+   *
+   * To render a controlled checkbox group, use the `value` prop instead.
+   */
+  defaultValue?: string[] | undefined;
+  /**
+   * Event handler called when a checkbox in the group is ticked or unticked.
+   * Provides the new value as an argument.
+   */
+  onValueChange?:
+    | ((value: string[], eventDetails: CheckboxGroup.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Names of all checkboxes in the group. Use this when creating a parent checkbox.
+   */
+  allValues?: string[] | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+}
+
+export type CheckboxGroupChangeEventReason = typeof REASONS.none;
+
+export type CheckboxGroupChangeEventDetails =
+  ZestChangeEventDetails<CheckboxGroupChangeEventReason>;
+
+export namespace CheckboxGroup {
+  export type State = CheckboxGroupState;
+  export type Props = CheckboxGroupProps;
+  export type ChangeEventReason = CheckboxGroupChangeEventReason;
+  export type ChangeEventDetails = CheckboxGroupChangeEventDetails;
+}

package/src/checkbox-group/CheckboxGroupContext.ts

@@ -0,0 +1,28 @@
+'use client';
+import * as React from 'react';
+import type { UseCheckboxGroupParentReturnValue } from './useCheckboxGroupParent';
+import type { ZestChangeEventDetails } from '../utils/createChangeEventDetails';
+import type { ZestEventReasons } from '../utils/reasons';
+
+export interface CheckboxGroupContext {
+  value: string[] | undefined;
+  defaultValue: string[] | undefined;
+  setValue: (
+    value: string[],
+    eventDetails: ZestChangeEventDetails<ZestEventReasons['none']>,
+  ) => void;
+  allValues: string[] | undefined;
+  parent: UseCheckboxGroupParentReturnValue;
+  disabled: boolean;
+}
+
+export const CheckboxGroupContext = React.createContext<CheckboxGroupContext | undefined>(
+  undefined,
+);
+
+/**
+ * Checkbox may be used standalone, so the group context is optional by design.
+ */
+export function useCheckboxGroupContext() {
+  return React.useContext(CheckboxGroupContext);
+}

package/src/checkbox-group/index.ts

@@ -0,0 +1,4 @@
+export { CheckboxGroup } from './CheckboxGroup';
+
+export type * from './CheckboxGroup';
+export { useCheckboxGroupContext } from './CheckboxGroupContext';