panelui-native 0.78.0 → 0.79.0

package/src/components/theme-selector/index.tsx

@@ -0,0 +1,281 @@
+/**
+ * ThemeSelector — light, dark, or whatever the device is set to.
+ *
+ * Three miniatures of a screen, the chosen one ringed. A row of words would
+ * take a third of the space and say the same thing, but "System" is the option
+ * people hesitate over, and a picture of a screen split down the middle
+ * explains it in less time than a sentence does.
+ *
+ * ```tsx
+ * <ThemeSelector label="Choose a theme" />
+ * ```
+ *
+ * ## It reads the theme rather than remembering it
+ *
+ * There is already one answer to "which theme is this" — Uniwind's — so the
+ * selector asks for it instead of keeping a copy that can disagree. Change the
+ * theme anywhere else in the app and the ring moves. Pass `value` to show
+ * something else, for a settings screen that stages a choice before applying
+ * it.
+ *
+ * ## Light and dark stay inside the family
+ *
+ * A reader in Moon who picks Light gets Moon's light theme, not the default
+ * one. System is the exception, and cannot be otherwise: the device knows only
+ * light and dark, so following it means following those two.
+ */
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react';
+import { Pressable, View, type PressableProps, type ViewProps } from 'react-native';
+import { tv } from 'tailwind-variants';
+import { useUniwind } from 'uniwind';
+import { Text, textChildren } from '../../primitives/text';
+import { useTheme, useThemeMode } from '../../theme/use-theme';
+import { ThemePreview, type ThemePreviewVariant } from './theme-preview';
+
+export type { ThemePreviewVariant } from './theme-preview';
+
+/** What the selector chooses between. */
+export type ThemeSelection = 'system' | 'light' | 'dark';
+
+/** How big the miniatures are drawn. */
+export type ThemeSelectorSize = 'sm' | 'md';
+
+/** The three, in the order a selector draws them when it is not told. */
+const OPTIONS: readonly ThemeSelection[] = ['system', 'light', 'dark'];
+
+/** What each one is called, when the caller does not say. */
+const LABELS: Record<ThemeSelection, string> = {
+  system: 'System',
+  light: 'Light',
+  dark: 'Dark',
+};
+
+/** How wide the miniature is drawn, per size. */
+const PREVIEW_WIDTH: Record<ThemeSelectorSize, number> = { sm: 72, md: 88 };
+
+const themeSelectorVariants = tv({
+  slots: {
+    root: 'gap-3',
+    legend: 'font-medium',
+    options: 'flex-row flex-wrap items-start gap-4',
+    option: 'items-center gap-2',
+    /*
+     * The ring lives on a box around the artwork rather than on the artwork
+     * itself. React Native has no outline, so a border on the preview would
+     * take a strip out of the drawing every time the option was chosen — the
+     * miniature would change size as you picked it.
+     */
+    frame: 'overflow-hidden rounded-xl border-2 p-1',
+    /*
+     * The artwork's own corners, rounded to sit concentrically inside the
+     * frame: the frame's radius less the padding between them. A square
+     * miniature inside a rounded ring reads as a screenshot somebody pasted in
+     * — the two edges have to curve together or neither should.
+     */
+    preview: 'overflow-hidden rounded-lg',
+    label: 'text-center',
+  },
+  variants: {
+    selected: {
+      true: { frame: 'border-primary', label: 'text-foreground' },
+      false: { frame: 'border-transparent', label: 'text-muted-foreground' },
+    },
+    disabled: {
+      true: { root: 'opacity-40' },
+    },
+  },
+  defaultVariants: { selected: false },
+});
+
+interface ThemeSelectorContextValue {
+  value: ThemeSelection;
+  select: (value: ThemeSelection) => void;
+  variant: ThemePreviewVariant;
+  size: ThemeSelectorSize;
+  disabled: boolean;
+}
+
+const ThemeSelectorContext = createContext<ThemeSelectorContextValue | null>(null);
+
+function useThemeSelector(part: string): ThemeSelectorContextValue {
+  const value = useContext(ThemeSelectorContext);
+  if (!value) throw new Error(`${part} must be used inside a <ThemeSelector>.`);
+  return value;
+}
+
+/**
+ * Which of the three the app is on, read from the theme itself.
+ *
+ * `hasAdaptiveThemes` is the part that makes this possible: it is true exactly
+ * while the theme is following the device, which is the one thing the theme's
+ * own name cannot tell you — `system` resolves to `light` or `dark` the moment
+ * it is applied, and the two are indistinguishable afterwards.
+ */
+export function useThemeSelection(): ThemeSelection {
+  const { hasAdaptiveThemes } = useUniwind();
+  const { mode } = useThemeMode();
+  return hasAdaptiveThemes ? 'system' : mode;
+}
+
+export interface ThemeSelectorProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /**
+   * Show this as chosen instead of whatever the app is actually on. For a
+   * settings screen that stages a choice before applying it; left unset, the
+   * selector reads the live theme.
+   */
+  value?: ThemeSelection;
+  /** Fires with the option pressed, before the theme changes. */
+  onValueChange?: (value: ThemeSelection) => void;
+  /**
+   * Apply the choice. On by default — a theme selector that does not select a
+   * theme is a radio group. Turn it off to store the choice and apply it
+   * yourself, which is what an app that persists the preference wants.
+   */
+  applyTheme?: boolean;
+  /** The heading above the row. Left out, there is none. */
+  label?: string;
+  /**
+   * Which miniature is drawn. `window` is an app screen with a panel on it;
+   * `card` is a framed card with an accent, cut on the diagonal for system.
+   */
+  variant?: ThemePreviewVariant;
+  /**
+   * How wide the miniatures are drawn. `sm` for a settings row that has other
+   * things on it; `md` when choosing the theme is what the screen is for.
+   */
+  size?: ThemeSelectorSize;
+  /** Stop the row being pressed, and dim it to say so. */
+  disabled?: boolean;
+  /**
+   * The options, in the order you want them. Left out, the selector draws
+   * system, light and dark in that order — which is the whole component.
+   */
+  children?: ReactNode;
+}
+
+function ThemeSelectorRoot({
+  className,
+  value,
+  onValueChange,
+  applyTheme = true,
+  label,
+  variant = 'window',
+  size = 'md',
+  disabled = false,
+  children,
+  ...props
+}: ThemeSelectorProps) {
+  const slots = themeSelectorVariants({ disabled });
+  const { setTheme } = useTheme();
+  const { setMode } = useThemeMode();
+  const live = useThemeSelection();
+  const current = value ?? live;
+
+  const select = useCallback(
+    (next: ThemeSelection) => {
+      onValueChange?.(next);
+      if (!applyTheme) return;
+      // `setMode` rather than `setTheme`, so a reader in a named family stays
+      // in it. Following the device is the one choice that cannot: the device
+      // has no opinion beyond light and dark.
+      if (next === 'system') setTheme('system');
+      else setMode(next);
+    },
+    [applyTheme, onValueChange, setTheme, setMode]
+  );
+
+  const context = useMemo<ThemeSelectorContextValue>(
+    () => ({ value: current, select, variant, size, disabled }),
+    [current, select, variant, size, disabled]
+  );
+
+  return (
+    <ThemeSelectorContext.Provider value={context}>
+      <View
+        accessibilityRole="radiogroup"
+        accessibilityLabel={label}
+        {...props}
+        className={slots.root({ className })}
+      >
+        {label ? (
+          <Text size="sm" className={slots.legend()}>
+            {label}
+          </Text>
+        ) : null}
+        <View className={slots.options()}>
+          {children
+            ? textChildren(children)
+            : OPTIONS.map((option) => (
+                <ThemeSelectorOption key={option} value={option} />
+              ))}
+        </View>
+      </View>
+    </ThemeSelectorContext.Provider>
+  );
+}
+
+export interface ThemeSelectorOptionProps
+  extends Omit<PressableProps, 'children' | 'onPress'> {
+  className?: string;
+  /** Which of the three this option chooses. */
+  value: ThemeSelection;
+  /** What it is called under the miniature. Defaults to System, Light or Dark. */
+  label?: string;
+  /** Replaces the drawn miniature. */
+  children?: ReactNode;
+}
+
+/**
+ * One of the three.
+ *
+ * The whole thing is the target — the miniature and the word under it — because
+ * at this size the word is the easier of the two to hit and pressing it should
+ * not miss.
+ */
+function ThemeSelectorOption({
+  className,
+  value,
+  label,
+  children,
+  ...props
+}: ThemeSelectorOptionProps) {
+  const context = useThemeSelector('ThemeSelector.Option');
+  const selected = context.value === value;
+  const slots = themeSelectorVariants({ selected, disabled: context.disabled });
+  const name = label ?? LABELS[value];
+
+  return (
+    <Pressable
+      accessibilityRole="radio"
+      accessibilityLabel={name}
+      accessibilityState={{ selected, disabled: context.disabled }}
+      disabled={context.disabled}
+      {...props}
+      onPress={() => context.select(value)}
+      className={slots.option({ className })}
+    >
+      <View className={slots.frame()}>
+        <View className={slots.preview()}>
+          {children ?? (
+            <ThemePreview
+              mode={value}
+              variant={context.variant}
+              width={PREVIEW_WIDTH[context.size]}
+            />
+          )}
+        </View>
+      </View>
+      <Text size="sm" className={slots.label()}>
+        {name}
+      </Text>
+    </Pressable>
+  );
+}
+
+ThemeSelectorRoot.displayName = 'ThemeSelector';
+ThemeSelectorOption.displayName = 'ThemeSelector.Option';
+
+export const ThemeSelector = Object.assign(ThemeSelectorRoot, {
+  Option: ThemeSelectorOption,
+});

package/src/components/theme-selector/theme-preview.tsx

@@ -0,0 +1,205 @@
+/**
+ * The three miniatures a theme selector is made of.
+ *
+ * Drawn from fixed neutrals rather than from theme tokens, which is the one
+ * thing about this file that is not obvious. A preview built out of the active
+ * theme's colours shows the reader the theme they already have, three times —
+ * the light option has to look light while the app around it is dark, or it is
+ * not a preview of anything.
+ *
+ * The greys are the ones a screenshot of an app would actually have: a ground,
+ * a surface sitting on it, a mark, and the lines of text. Two sets, and the
+ * system option draws both.
+ */
+import { useId, type ReactNode } from 'react';
+import Svg, { Circle, ClipPath, Defs, G, Path, Rect } from 'react-native-svg';
+
+/** Which of the three a preview is drawing. */
+export type ThemePreviewMode = 'system' | 'light' | 'dark';
+
+/** How the miniature is drawn. */
+export type ThemePreviewVariant = 'window' | 'card';
+
+interface Palette {
+  /** Behind everything — the desktop, the page, the space around the app. */
+  ground: string;
+  /** The app's own surface. */
+  surface: string;
+  /** A shape on it: an avatar, an image, a control. */
+  mark: string;
+  /** Lines of text. */
+  line: string;
+}
+
+const PALETTE: Record<'light' | 'dark', Palette> = {
+  light: { ground: '#e5e5e5', surface: '#ffffff', mark: '#d4d4d4', line: '#e5e5e5' },
+  dark: { ground: '#171717', surface: '#262626', mark: '#525252', line: '#404040' },
+};
+
+/**
+ * The one colour that is not a grey.
+ *
+ * Fixed for the same reason the greys are, and warm rather than blue: it has to
+ * read as "a colour in the app" on both grounds without looking like the ring
+ * that marks the chosen option.
+ */
+const ACCENT = '#c1704f';
+
+/** Everything is drawn in this box and scaled by the container. */
+const VIEW_BOX = { width: 88, height: 70 };
+
+/**
+ * The lower-right half of the box, cut from the top-right corner to the
+ * bottom-left one. Both text lines sit above it and the accent below it, which
+ * is what makes one card show a light screen and a dark one at the same time.
+ */
+const DIAGONAL = `M${VIEW_BOX.width} 0V${VIEW_BOX.height}H0Z`;
+
+/* -------------------------------------------------------------------------- *
+ * window — an app screen, with the panel inset from the leading edge
+ * -------------------------------------------------------------------------- */
+
+function WindowHalf({ palette, side }: { palette: Palette; side: 'left' | 'right' | 'full' }) {
+  if (side === 'full') {
+    return (
+      <>
+        <Rect x={0} y={0} width={88} height={70} fill={palette.ground} />
+        <Path d="M10 12a4 4 0 0 1 4-4h74v62H10V12Z" fill={palette.surface} />
+        <Circle cx={28} cy={26} r={8} fill={palette.mark} />
+        <Rect x={20} y={42} width={58} height={4} rx={2} fill={palette.line} />
+        <Rect x={20} y={49} width={58} height={4} rx={2} fill={palette.line} />
+        <Rect x={20} y={56} width={29} height={4} rx={2} fill={palette.line} />
+      </>
+    );
+  }
+
+  /*
+   * Half a screen each, and the halves are not mirror images: the panel starts
+   * at the same inset on the left and runs to the edge on the right, so the
+   * seam falls where the two app surfaces meet rather than down the middle of
+   * one of them.
+   */
+  const x = side === 'left' ? 0 : 44;
+  return (
+    <>
+      <Rect x={x} y={0} width={44} height={70} fill={palette.ground} />
+      {side === 'left' ? (
+        <>
+          <Path d="M10 12a4 4 0 0 1 4-4h30v62H10V12Z" fill={palette.surface} />
+          <Circle cx={28} cy={26} r={8} fill={palette.mark} />
+          <Rect x={20} y={42} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={20} y={49} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={20} y={56} width={24} height={4} rx={2} fill={palette.line} />
+        </>
+      ) : (
+        <>
+          <Path d="M54 12a4 4 0 0 1 4-4h30v62H54V12Z" fill={palette.surface} />
+          <Circle cx={72} cy={26} r={8} fill={palette.mark} />
+          <Rect x={64} y={42} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={64} y={49} width={24} height={4} rx={2} fill={palette.line} />
+          <Rect x={64} y={56} width={24} height={4} rx={2} fill={palette.line} />
+        </>
+      )}
+    </>
+  );
+}
+
+/* -------------------------------------------------------------------------- *
+ * card — a framed card, with an accent on it
+ * -------------------------------------------------------------------------- */
+
+/*
+ * The card fills its box rather than floating inside it.
+ *
+ * It used to carry a margin of its own, which then sat on top of the padding
+ * between the artwork and the ring around it — two gaps doing one job, and the
+ * bigger the miniature the further apart they held the two edges.
+ */
+const CARD_FRAME = { x: 0, y: 0, width: 88, height: 70, rx: 16 } as const;
+const CARD_SURFACE = { x: 8, y: 8, width: 72, height: 54, rx: 10 } as const;
+
+function CardBody({ palette }: { palette: Palette }) {
+  return (
+    <>
+      <Rect {...CARD_FRAME} fill={palette.ground} />
+      <Rect {...CARD_SURFACE} fill={palette.surface} />
+      <Rect x={17} y={18} width={34} height={4} rx={2} fill={palette.line} />
+      <Rect x={17} y={26} width={23} height={4} rx={2} fill={palette.line} />
+    </>
+  );
+}
+
+export interface ThemePreviewProps {
+  mode: ThemePreviewMode;
+  variant?: ThemePreviewVariant;
+  width: number;
+}
+
+/**
+ * One miniature.
+ *
+ * `width` rather than a scale factor: the option's box is what decides the
+ * size, and everything inside is drawn against a fixed box and scaled by the
+ * viewBox — so the geometry above never has to know how big it ended up.
+ */
+export function ThemePreview({ mode, variant = 'window', width }: ThemePreviewProps): ReactNode {
+  const height = Math.round((width / VIEW_BOX.width) * VIEW_BOX.height);
+  /*
+   * `useId` returns something with colons in it, which is not a name an SVG
+   * fragment reference accepts — a clip that silently fails to resolve draws
+   * nothing at all, and on a shape covering half the artwork that is the whole
+   * option missing.
+   */
+  const clip = `panelui-theme-${useId().replace(/[^a-zA-Z0-9-]/g, '')}`;
+
+  if (variant === 'card') {
+    return (
+      <Svg width={width} height={height} viewBox="0 0 88 70">
+        <CardBody palette={PALETTE[mode === 'dark' ? 'dark' : 'light']} />
+
+        {mode === 'system' ? (
+          <>
+            {/*
+              The other half, cut corner to corner.
+              
+              The same triangle twice, clipped once to the frame and once to
+              the card inside it, rather than one shape tracing where the
+              diagonal crosses both. Two clips is less arithmetic than one path
+              and stays right if either radius changes; an unclipped triangle
+              squares off the two corners the diagonal runs into.
+            */}
+            <Defs>
+              <ClipPath id={`${clip}-frame`}>
+                <Rect {...CARD_FRAME} />
+              </ClipPath>
+              <ClipPath id={`${clip}-card`}>
+                <Rect {...CARD_SURFACE} />
+              </ClipPath>
+            </Defs>
+            <G clipPath={`url(#${clip}-frame)`}>
+              <Path d={DIAGONAL} fill={PALETTE.dark.ground} />
+            </G>
+            <G clipPath={`url(#${clip}-card)`}>
+              <Path d={DIAGONAL} fill={PALETTE.dark.surface} />
+            </G>
+          </>
+        ) : null}
+
+        <Circle cx={64} cy={47} r={8} fill={ACCENT} />
+      </Svg>
+    );
+  }
+
+  return (
+    <Svg width={width} height={height} viewBox="0 0 88 70">
+      {mode === 'system' ? (
+        <>
+          <WindowHalf palette={PALETTE.light} side="left" />
+          <WindowHalf palette={PALETTE.dark} side="right" />
+        </>
+      ) : (
+        <WindowHalf palette={PALETTE[mode]} side="full" />
+      )}
+    </Svg>
+  );
+}

package/src/index.ts

@@ -538,6 +538,9 @@ export {
   type PanelsideGroupProps,
   type PanelsideGroupLabelProps,
   type PanelsideItemProps,
+  type PanelsideItemIconProps,
+  type PanelsideItemLabelProps,
+  type PanelsideItemBadgeProps,
   type PanelsideActionProps,
   type PanelsideFooterProps,
   type PanelsideCtaProps,
@@ -658,6 +661,15 @@ export {
   type ChartPoint,
 } from './components/plot';
 export { Textarea, type TextareaProps } from './components/textarea';
+export {
+  ThemeSelector,
+  useThemeSelection,
+  type ThemeSelectorProps,
+  type ThemeSelectorOptionProps,
+  type ThemeSelection,
+  type ThemeSelectorSize,
+  type ThemePreviewVariant,
+} from './components/theme-selector';
 export {
   TagInput,
   type TagInputProps,
@@ -730,8 +742,10 @@ export {
   type MarkdownEditorToolbarProps,
   type MarkdownEditorInputProps,
   type MarkdownEditorPreviewProps,
+  type MarkdownEditorHandle,
   type MarkdownEditorMode,
   type MarkdownEditorAction,
+  type MarkdownEditorToolbarVariant,
   type EditorSelection,
   type EditResult,
 } from './components/markdown-editor';
@@ -849,6 +863,7 @@ export {
   useProgressButton,
   type ProgressButtonProps,
   type ProgressButtonLabelProps,
+  type ProgressButtonDoneProps,
   type ProgressButtonVariant,
   type ProgressButtonSize,
 } from './components/progress-button';