panelui-native 0.16.0 → 0.19.0

package/src/components/form/index.tsx

@@ -0,0 +1,85 @@
+/**
+ * Form — binds a `useForm` instance to its fields without threading `form`
+ * through every one of them by hand.
+ *
+ * `Form.Field` is a render prop, not a component that clones its child, for
+ * the same reason `useField` is a hook and not a wrapper: PanelUI's controls
+ * take differently-shaped change props, and only the caller knows which one
+ * a given field needs to wire up.
+ *
+ * `Form`/`Form.Field` trade some type precision for that JSX ergonomics — a
+ * field's `name` isn't checked against `keyof YourValues` here, because a
+ * value's shape can't flow through `useContext` generically. Reach for
+ * `useField(form, name)` directly when a field's name should be checked
+ * against the form's own value type.
+ *
+ * ```tsx
+ * const form = useForm({
+ *   defaultValues: { email: '' },
+ *   onSubmit: async (values) => { ... },
+ * });
+ *
+ * <Form form={form}>
+ *   <Form.Field name="email" validate={(value) => (value ? undefined : 'Required')}>
+ *     {(field) => (
+ *       <Input
+ *         label="Email"
+ *         value={field.value}
+ *         onChangeText={field.onChange}
+ *         onBlur={field.onBlur}
+ *         errorMessage={field.error}
+ *       />
+ *     )}
+ *   </Form.Field>
+ * </Form>
+ * ```
+ */
+import { createContext, useContext, type ReactNode } from 'react';
+import { useField, type FormFieldRenderProps, type UseFieldOptions } from './use-field';
+import { useForm, type FormApi, type FieldErrors, type FieldTouched, type FieldState, type UseFormOptions, type Validator } from './use-form';
+
+export { useForm, useField };
+export type {
+  FormApi,
+  FieldErrors,
+  FieldTouched,
+  FieldState,
+  UseFormOptions,
+  Validator,
+  FormFieldRenderProps,
+  UseFieldOptions,
+};
+
+const FormContext = createContext<FormApi<any> | null>(null);
+
+export interface FormProps {
+  form: FormApi<any>;
+  children?: ReactNode;
+}
+
+function FormRoot({ form, children }: FormProps) {
+  return <FormContext.Provider value={form}>{children}</FormContext.Provider>;
+}
+FormRoot.displayName = 'Form';
+
+export interface FormFieldProps {
+  name: string;
+  validate?: (value: any, values: any) => string | undefined | Promise<string | undefined>;
+  /** Runs on blur, and always on submit. `'change'` also validates on every edit. */
+  validateOn?: 'blur' | 'change';
+  children: (field: FormFieldRenderProps<any>) => ReactNode;
+}
+
+function FormField({ name, validate, validateOn, children }: FormFieldProps) {
+  const form = useContext(FormContext);
+  if (!form) {
+    throw new Error('Form.Field must be rendered inside a <Form>.');
+  }
+  const field = useField(form, name, { validate, validateOn });
+  return <>{children(field)}</>;
+}
+FormField.displayName = 'Form.Field';
+
+export const Form = Object.assign(FormRoot, {
+  Field: FormField,
+});

package/src/components/form/use-field.ts

@@ -0,0 +1,65 @@
+/**
+ * useField — binds one `useForm` field to a control's own props.
+ *
+ * A hook rather than a component that clones its child, because PanelUI's
+ * controls each take a differently-shaped change prop — `onChangeText` on
+ * `Input`, `onCheckedChange` on `Checkbox`, `onValueChange` on `Switch` and
+ * `RadioGroup` — so the caller is the one who knows which to wire `onChange`
+ * to. `Form.Field` is a thin JSX wrapper around this same hook, for callers
+ * who prefer a render prop to calling a hook per field.
+ */
+import { useEffect, useRef } from 'react';
+import type { FormApi, Validator } from './use-form';
+
+export interface FormFieldRenderProps<V> {
+  value: V;
+  /** Only set once the field has been touched (blurred, or the form submitted). */
+  error?: string;
+  touched: boolean;
+  onChange: (value: V) => void;
+  onBlur: () => void;
+}
+
+export interface UseFieldOptions<T extends Record<string, any>, K extends keyof T> {
+  validate?: Validator<T, K>;
+  /** Runs on blur, and always on submit. `'change'` also validates on every edit. */
+  validateOn?: 'blur' | 'change';
+}
+
+export function useField<T extends Record<string, any>, K extends keyof T>(
+  form: FormApi<T>,
+  name: K,
+  { validate, validateOn = 'blur' }: UseFieldOptions<T, K> = {}
+): FormFieldRenderProps<T[K]> {
+  // Kept fresh every render without retriggering the registration effect —
+  // an inline validator function has a new identity on every render, and
+  // re-registering on every one of those would be wasted work.
+  const validateRef = useRef(validate);
+  validateRef.current = validate;
+
+  const { registerValidator } = form;
+  useEffect(() => {
+    registerValidator(
+      name,
+      validate ? (value, values) => validateRef.current!(value, values) : undefined
+    );
+    return () => registerValidator(name, undefined);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [registerValidator, name, !!validate]);
+
+  const { value, error, touched } = form.getFieldState(name);
+
+  return {
+    value,
+    error: touched ? error : undefined,
+    touched,
+    onChange: (next: T[K]) => {
+      form.setFieldValue(name, next);
+      if (validateOn === 'change') form.validateField(name);
+    },
+    onBlur: () => {
+      form.setFieldTouched(name, true);
+      if (validateOn === 'blur') form.validateField(name);
+    },
+  };
+}

package/src/components/form/use-form.ts

@@ -0,0 +1,252 @@
+/**
+ * useForm — form state for React Native, with no form library underneath.
+ *
+ * Values, errors and touched state live in one `useReducer` so a single
+ * dispatch can update more than one of them atomically — setting a value
+ * also clears that field's error in the same update, so a field being fixed
+ * never flashes invalid for one extra frame while the two states catch up
+ * with each other.
+ *
+ * Per-field validators are not passed in here. They register themselves —
+ * `useField`/`Form.Field` do this — because the field that owns the
+ * validation rule is usually rendered far from the `useForm` call, and
+ * threading every field's validator up to one options object would mean
+ * `useForm`'s call site has to know about every field in the tree. What is
+ * passed in here (`validate`) is whole-form validation: cross-field rules
+ * like "confirm password must match password".
+ *
+ * Only flat, JSON-serializable values are supported — string, number,
+ * boolean, and plain arrays/objects of those. There is no field-array helper
+ * (`useFieldArray`) in this version; model a repeating group with your own
+ * `useState` array of ids and one `useForm` per row, or key a field's name
+ * with an index (`"emails.0"`) and treat it as an opaque string.
+ *
+ * `defaultValues` is read once, on the first render. If default values
+ * arrive asynchronously, mount the form once you have them (e.g. behind a
+ * loading check) rather than expecting the hook to pick up a later change.
+ */
+import { useCallback, useMemo, useReducer, useRef } from 'react';
+
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+export type FieldTouched<T> = Partial<Record<keyof T, boolean>>;
+
+export type Validator<T extends Record<string, any>, K extends keyof T> = (
+  value: T[K],
+  values: T
+) => string | undefined | Promise<string | undefined>;
+
+export interface FieldState<V> {
+  value: V;
+  error?: string;
+  touched: boolean;
+}
+
+export interface UseFormOptions<T extends Record<string, any>> {
+  defaultValues: T;
+  /** Whole-form validation, e.g. a rule that compares two fields. Runs on submit. */
+  validate?: (values: T) => FieldErrors<T> | Promise<FieldErrors<T>>;
+  onSubmit: (values: T) => void | Promise<void>;
+}
+
+export interface FormApi<T extends Record<string, any>> {
+  values: T;
+  errors: FieldErrors<T>;
+  touched: FieldTouched<T>;
+  isSubmitting: boolean;
+  /** No field currently carries a validation error. Fields validate on blur and
+   * submit, so this does not guarantee an untouched field would pass. */
+  isValid: boolean;
+  /** `values` differs from `defaultValues`, compared as JSON. */
+  isDirty: boolean;
+  setFieldValue: <K extends keyof T>(name: K, value: T[K]) => void;
+  setFieldTouched: <K extends keyof T>(name: K, touched?: boolean) => void;
+  setFieldError: <K extends keyof T>(name: K, error: string | undefined) => void;
+  getFieldState: <K extends keyof T>(name: K) => FieldState<T[K]>;
+  /** Used by `useField`/`Form.Field` to attach a field's validation rule. */
+  registerValidator: <K extends keyof T>(name: K, validator?: Validator<T, K>) => void;
+  /** Runs `name`'s registered validator (if any) and records the result. */
+  validateField: <K extends keyof T>(name: K) => Promise<boolean>;
+  handleSubmit: () => Promise<void>;
+  reset: (values?: T) => void;
+}
+
+interface State<T> {
+  values: T;
+  errors: FieldErrors<T>;
+  touched: FieldTouched<T>;
+  isSubmitting: boolean;
+}
+
+type Action<T> =
+  | { type: 'SET_VALUE'; name: keyof T; value: unknown }
+  | { type: 'SET_TOUCHED'; name: keyof T; touched: boolean }
+  | { type: 'SET_ERROR'; name: keyof T; error: string | undefined }
+  | { type: 'SET_ERRORS'; errors: FieldErrors<T> }
+  | { type: 'TOUCH_ALL'; names: (keyof T)[] }
+  | { type: 'SUBMIT_START' }
+  | { type: 'SUBMIT_END' }
+  | { type: 'RESET'; values: T };
+
+function reducer<T extends Record<string, any>>(
+  state: State<T>,
+  action: Action<T>
+): State<T> {
+  switch (action.type) {
+    case 'SET_VALUE':
+      return {
+        ...state,
+        values: { ...state.values, [action.name]: action.value } as T,
+        errors: { ...state.errors, [action.name]: undefined },
+      };
+    case 'SET_TOUCHED':
+      return {
+        ...state,
+        touched: { ...state.touched, [action.name]: action.touched },
+      };
+    case 'SET_ERROR':
+      return { ...state, errors: { ...state.errors, [action.name]: action.error } };
+    case 'SET_ERRORS':
+      return { ...state, errors: { ...state.errors, ...action.errors } };
+    case 'TOUCH_ALL': {
+      const touched = { ...state.touched };
+      for (const name of action.names) touched[name] = true;
+      return { ...state, touched };
+    }
+    case 'SUBMIT_START':
+      return { ...state, isSubmitting: true };
+    case 'SUBMIT_END':
+      return { ...state, isSubmitting: false };
+    case 'RESET':
+      return { values: action.values, errors: {}, touched: {}, isSubmitting: false };
+    default:
+      return state;
+  }
+}
+
+export function useForm<T extends Record<string, any>>({
+  defaultValues,
+  validate,
+  onSubmit,
+}: UseFormOptions<T>): FormApi<T> {
+  const defaultsRef = useRef(defaultValues);
+  const validatorsRef = useRef<
+    Partial<Record<keyof T, (value: any, values: T) => string | undefined | Promise<string | undefined>>>
+  >({});
+
+  const [state, dispatch] = useReducer(reducer<T>, {
+    values: defaultValues,
+    errors: {},
+    touched: {},
+    isSubmitting: false,
+  });
+
+  const setFieldValue = useCallback(<K extends keyof T>(name: K, value: T[K]) => {
+    dispatch({ type: 'SET_VALUE', name, value });
+  }, []);
+
+  const setFieldTouched = useCallback(<K extends keyof T>(name: K, touched = true) => {
+    dispatch({ type: 'SET_TOUCHED', name, touched });
+  }, []);
+
+  const setFieldError = useCallback(
+    <K extends keyof T>(name: K, error: string | undefined) => {
+      dispatch({ type: 'SET_ERROR', name, error });
+    },
+    []
+  );
+
+  const registerValidator = useCallback(
+    <K extends keyof T>(name: K, validator?: Validator<T, K>) => {
+      if (validator) {
+        validatorsRef.current[name] = validator;
+      } else {
+        delete validatorsRef.current[name];
+      }
+    },
+    []
+  );
+
+  const getFieldState = useCallback(
+    <K extends keyof T>(name: K): FieldState<T[K]> => ({
+      value: state.values[name],
+      error: state.errors[name],
+      touched: !!state.touched[name],
+    }),
+    [state.values, state.errors, state.touched]
+  );
+
+  const validateField = useCallback(
+    async <K extends keyof T>(name: K) => {
+      const validator = validatorsRef.current[name];
+      if (!validator) return true;
+      const error = await validator(state.values[name], state.values);
+      dispatch({ type: 'SET_ERROR', name, error });
+      return !error;
+    },
+    [state.values]
+  );
+
+  const handleSubmit = useCallback(async () => {
+    const names = Object.keys(state.values) as (keyof T)[];
+    dispatch({ type: 'TOUCH_ALL', names });
+
+    const fieldErrorEntries = await Promise.all(
+      names.map(async (name) => {
+        const validator = validatorsRef.current[name];
+        const error = validator
+          ? await validator(state.values[name], state.values)
+          : undefined;
+        return [name, error] as const;
+      })
+    );
+
+    const formErrors = validate ? await validate(state.values) : {};
+
+    const cleared = Object.fromEntries(names.map((name) => [name, undefined]));
+    const nextErrors: FieldErrors<T> = {
+      ...cleared,
+      ...Object.fromEntries(fieldErrorEntries.filter(([, error]) => error !== undefined)),
+      ...formErrors,
+    };
+    dispatch({ type: 'SET_ERRORS', errors: nextErrors });
+
+    if (Object.values(nextErrors).some(Boolean)) return;
+
+    dispatch({ type: 'SUBMIT_START' });
+    try {
+      await onSubmit(state.values);
+    } finally {
+      dispatch({ type: 'SUBMIT_END' });
+    }
+  }, [state.values, validate, onSubmit]);
+
+  const reset = useCallback((values: T = defaultsRef.current) => {
+    dispatch({ type: 'RESET', values });
+  }, []);
+
+  const isDirty = useMemo(
+    () => JSON.stringify(state.values) !== JSON.stringify(defaultsRef.current),
+    [state.values]
+  );
+  const isValid = useMemo(
+    () => Object.values(state.errors).every((error) => !error),
+    [state.errors]
+  );
+
+  return {
+    values: state.values,
+    errors: state.errors,
+    touched: state.touched,
+    isSubmitting: state.isSubmitting,
+    isValid,
+    isDirty,
+    setFieldValue,
+    setFieldTouched,
+    setFieldError,
+    getFieldState,
+    registerValidator,
+    validateField,
+    handleSubmit,
+    reset,
+  };
+}

package/src/components/frame/index.tsx

@@ -21,8 +21,14 @@
  *     <Frame.Action>All agents under 25% token limit</Frame.Action>
  *   </Frame.Header>
  *   <Frame.Panel>
- *     <Frame.Row>…</Frame.Row>
- *     <Frame.Row>…</Frame.Row>
+ *     <Frame.Row>
+ *       <Frame.Media><PackageIcon /></Frame.Media>
+ *       <Frame.Content>
+ *         <Frame.Title>opus-4.6</Frame.Title>
+ *         <Frame.Description>Indexing the repository</Frame.Description>
+ *       </Frame.Content>
+ *       <Frame.Actions><Chip>Running</Chip></Frame.Actions>
+ *     </Frame.Row>
  *   </Frame.Panel>
  * </Frame>
  * ```
@@ -30,8 +36,24 @@
  * The panel draws the hairlines between its own rows. React Native has no
  * `:first-child`, so the alternative is every caller writing
  * `divided={index > 0}` on every row and getting it wrong once.
+ *
+ * A row is three slots, and they exist because of one React Native detail:
+ * Yoga defaults `flexShrink` to `0`, the opposite of the web. A child that is
+ * not told to shrink never does, so a fourth thing in a row pushes the others
+ * past the edge — where the frame's `overflow-hidden` silently cuts them off
+ * rather than wrapping or truncating. `Frame.Media` and `Frame.Actions` hold
+ * their size, `Frame.Content` takes what is left and is allowed to shrink to
+ * nothing, and the row fits at any width without the caller measuring anything.
  */
-import { Children, cloneElement, forwardRef, isValidElement, type ReactNode } from 'react';
+import {
+  Children,
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  type ReactNode,
+} from 'react';
 import {
   Pressable,
   View,
@@ -74,6 +96,14 @@ const frameVariants = tv({
 
 export type FrameVariant = 'default' | 'plain';
 
+/**
+ * True inside a `Frame.Content`. The header's caption and a row's title are the
+ * same part in two places and only the placement decides the weight: a header
+ * labels the tray the card sits in, so it stays quiet, while a row title is the
+ * row's subject and has to carry it.
+ */
+const FrameSlotContext = createContext(false);
+
 export interface FrameProps extends ViewProps {
   className?: string;
 }
@@ -107,6 +137,8 @@ const FrameHeader = forwardRef<View, FrameHeaderProps>(
     <View
       ref={ref}
       className={cn(
+        // `min-w-0` on nothing here — the title itself takes the flexible side,
+        // so a long one truncates instead of shoving the action off the edge.
         'flex-row items-center justify-between gap-3 px-4 pb-3 pt-2.5',
         className
       )}
@@ -117,12 +149,31 @@ const FrameHeader = forwardRef<View, FrameHeaderProps>(
 FrameHeader.displayName = 'Frame.Header';
 
 /**
- * Muted by default. The header is a caption on the tray the card sits in, not
- * a heading over a section — the card's own rows carry the weight.
+ * Muted in a header, where it is a caption on the tray the card sits in. Inside
+ * a `Frame.Content` it is the row's subject instead, so it takes the foreground
+ * colour and medium weight, and truncates to one line rather than pushing the
+ * row's trailing slot out of view. Pass `numberOfLines` to override either way.
  */
-const FrameTitle = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => (
-  <Text ref={ref} size="sm" muted className={className} {...props} />
-));
+const FrameTitle = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => {
+  const inRow = useContext(FrameSlotContext);
+
+  if (inRow) {
+    return (
+      <Text
+        ref={ref}
+        size="sm"
+        weight="medium"
+        numberOfLines={1}
+        className={className}
+        {...props}
+      />
+    );
+  }
+
+  return (
+    <Text ref={ref} size="sm" muted className={cn('min-w-0 shrink', className)} {...props} />
+  );
+});
 FrameTitle.displayName = 'Frame.Title';
 
 export interface FrameActionProps extends FrameProps {
@@ -135,7 +186,11 @@ export interface FrameActionProps extends FrameProps {
  */
 const FrameAction = forwardRef<View, FrameActionProps>(
   ({ className, children, ...props }, ref) => (
-    <View ref={ref} className={cn('flex-row items-center gap-2', className)} {...props}>
+    <View
+      ref={ref}
+      className={cn('shrink-0 flex-row items-center gap-2', className)}
+      {...props}
+    >
       {typeof children === 'string' ? (
         <Text size="sm" muted>
           {children}
@@ -148,13 +203,87 @@ const FrameAction = forwardRef<View, FrameActionProps>(
 );
 FrameAction.displayName = 'Frame.Action';
 
-/** Secondary line under the title, inside a column-wrapped header. */
+/**
+ * Secondary line under the title — in a column-wrapped header, or under a row's
+ * title inside `Frame.Content`, where it drops a size and wraps to two lines.
+ */
 const FrameDescription = forwardRef<RNText, TextProps>(
+  ({ className, ...props }, ref) => {
+    const inRow = useContext(FrameSlotContext);
+
+    return (
+      <Text
+        ref={ref}
+        size={inRow ? 'xs' : 'sm'}
+        muted
+        numberOfLines={inRow ? 2 : undefined}
+        className={className}
+        {...props}
+      />
+    );
+  }
+);
+FrameDescription.displayName = 'Frame.Description';
+
+export interface FrameMediaProps extends FrameProps {
+  children?: ReactNode;
+}
+
+/**
+ * Leading slot on a row — an icon, an avatar, a status dot. Holds its size, so
+ * whatever it holds is never squeezed by the text beside it.
+ */
+const FrameMedia = forwardRef<View, FrameMediaProps>(
   ({ className, ...props }, ref) => (
-    <Text ref={ref} size="sm" muted className={className} {...props} />
+    <View
+      ref={ref}
+      className={cn('shrink-0 items-center justify-center', className)}
+      {...props}
+    />
   )
 );
-FrameDescription.displayName = 'Frame.Description';
+FrameMedia.displayName = 'Frame.Media';
+
+export interface FrameContentProps extends FrameProps {
+  children?: ReactNode;
+}
+
+/**
+ * The flexible middle of a row — usually a `Frame.Title` over a
+ * `Frame.Description`. It takes whatever the media and actions leave and is
+ * allowed to shrink past its content, which is what keeps a long line from
+ * pushing the rest of the row off the edge.
+ */
+const FrameContent = forwardRef<View, FrameContentProps>(
+  ({ className, children, ...props }, ref) => (
+    // `min-w-0` is the whole trick: a flex child's minimum size is its content
+    // unless told otherwise, so `flex-1` alone still refuses to go narrower
+    // than the longest word in it.
+    <View ref={ref} className={cn('min-w-0 flex-1 gap-0.5', className)} {...props}>
+      <FrameSlotContext.Provider value>{children}</FrameSlotContext.Provider>
+    </View>
+  )
+);
+FrameContent.displayName = 'Frame.Content';
+
+export interface FrameActionsProps extends FrameProps {
+  children?: ReactNode;
+}
+
+/**
+ * Trailing slot on a row — a chip, a value, a switch, a small button. Holds its
+ * size, so it stays readable however long the content beside it runs.
+ */
+const FrameActions = forwardRef<View, FrameActionsProps>(
+  ({ className, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn('shrink-0 flex-row items-center gap-1.5', className)}
+      {...props}
+    />
+  )
+);
+FrameActions.displayName = 'Frame.Actions';
 
 /**
  * Marks the parts that take part in the panel's own divider bookkeeping —
@@ -212,6 +341,17 @@ export interface FrameRowProps extends Omit<PressableProps, 'children'>, Dividab
   divided?: boolean;
   /** Trailing chevron marking the row as leading somewhere. */
   chevron?: boolean;
+  /**
+   * Let the row run onto a second line instead of holding one. For a cluster
+   * of chips or tags, where the alternative is the last ones being clipped.
+   */
+  wrap?: boolean;
+  /**
+   * Where the row's slots sit against each other. `start` for a row two or
+   * three lines tall, where centring an icon against a tall text column leaves
+   * it floating in the middle.
+   */
+  align?: 'center' | 'start';
   children?: ReactNode;
 }
 
@@ -221,9 +361,14 @@ export interface FrameRowProps extends Omit<PressableProps, 'children'>, Dividab
  * handler bolted on.
  */
 const FrameRow = forwardRef<View, FrameRowProps>(
-  ({ className, divided, chevron, children, onPress, ...props }, ref) => {
+  (
+    { className, divided, chevron, wrap, align = 'center', children, onPress, ...props },
+    ref
+  ) => {
     const classes = cn(
-      'flex-row items-center gap-3 px-4 py-3.5',
+      'flex-row gap-3 px-4 py-3.5',
+      align === 'start' ? 'items-start' : 'items-center',
+      wrap && 'flex-wrap',
       divided && 'border-t border-border',
       onPress && 'active:bg-muted',
       className
@@ -306,4 +451,7 @@ export const Frame = Object.assign(FrameRoot, {
   Panel: FramePanel,
   Section: FrameSection,
   Row: FrameRow,
+  Media: FrameMedia,
+  Content: FrameContent,
+  Actions: FrameActions,
 });