@krapwoo/ds-viewer 0.1.0 → 0.2.0

package/starter-kit/components/Pill/Pill.tsx

@@ -0,0 +1,181 @@
+import React, { useState } from 'react';
+import { Pressable, Text, StyleSheet, View } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_SHADOW } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { Loading } from '../Loading';
+import type { PillProps } from './Pill.types';
+
+function PillIcon({
+  name,
+  selected,
+  size = 16,
+}: {
+  name: NonNullable<PillProps['iconName']>;
+  selected: boolean;
+  size?: number;
+}) {
+  return (
+    <Icon name={name} size={size} color={selected ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular} />
+  );
+}
+
+/**
+ * A single-line selection chip. `selected` fills solid dark with inverse content; `not_selected`
+ * sits on white with a resting shadow. Leading slot holds an `iconName`, a custom `icon` node
+ * (sizes naturally), or the default menu icon; the label can be hidden for an icon-only pill.
+ */
+export function Pill({
+  label = 'Text',
+  variant = 'selected',
+  accessibilityLabel,
+  showText = true,
+  iconName,
+  iconSize = 16,
+  icon,
+  onPress,
+  disabled = false,
+  loading = false,
+  style,
+}: PillProps) {
+  const isSelected = variant === 'selected';
+  const isDisabled = disabled || loading;
+  const [focused, setFocused] = useState(false);
+
+  // A custom `icon` node (e.g. a badge) is taller than a plain icon. The pill keeps a fixed
+  // height regardless, so the badge centers in the same height as an icon+label pill; its horizontal
+  // padding is then reduced to equal the (smaller) vertical breathing room around the taller badge.
+  const isBadge = !iconName && icon != null;
+
+  // The leading slot sizes to its content, so it holds an `iconName` (at `iconSize`), a custom `icon`
+  // node of any size, or the default menu icon.
+  const iconNode = iconName ? (
+    <PillIcon name={iconName} selected={isSelected} size={iconSize} />
+  ) : (
+    icon ?? <PillIcon name="menu" selected={isSelected} size={iconSize} />
+  );
+
+  const content = loading ? (
+    <Loading
+      size={16}
+      color={isSelected ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular}
+    />
+  ) : (
+    <>
+      <View style={styles.iconSlot}>{iconNode}</View>
+      {showText && label ? (
+        <Text
+          // Pills are single-line chips — never wrap (a sub-pixel-tight equal width would otherwise
+          // fold the label onto two lines and grow the pill).
+          numberOfLines={1}
+          style={[
+            styles.label,
+            { color: isSelected ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular },
+          ]}
+        >
+          {label}
+        </Text>
+      ) : null}
+    </>
+  );
+
+  // Icon-only pills are forced to a fixed width equal to the pill's own fixed height (not left to
+  // emerge from padding + the icon's own width, which only happens to land on a square at the
+  // default iconSize=16 — passing a different `iconSize` would otherwise stretch it into a
+  // rounded rect instead of a true circle) — a fixed square, with content centred inside it via the
+  // container's own `alignItems`/`justifyContent: center`, keeps it circular at any icon size.
+  const containerStyle = [
+    styles.container,
+    showText ? { paddingHorizontal: isBadge ? DS_SPACING[400] : DS_SPACING[600] } : styles.iconOnly,
+    isSelected ? styles.selected : styles.notSelected,
+    isDisabled && styles.disabled,
+    style,
+  ];
+
+  // A selected pill is the current state — tapping it is a no-op, so it renders as a plain View
+  // (no pressed feedback) even when an onPress is wired up.
+  if (onPress && !isSelected) {
+    return (
+      <Pressable
+        onPress={onPress}
+        disabled={isDisabled}
+        // Extends the 40pt-tall pill to the 44pt minimum touch target. An icon-only pill is also only
+        // ~40pt wide (no label to widen it), so it needs the same padding on left/right too.
+        hitSlop={showText ? { top: 2, bottom: 2 } : { top: 2, bottom: 2, left: 2, right: 2 }}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel ?? label}
+        accessibilityState={{ disabled: isDisabled, busy: loading, selected: isSelected }}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        style={({ pressed }) => [
+          containerStyle,
+          pressed && !isDisabled && styles.pressed,
+          focused && !isDisabled && styles.focused,
+        ]}
+      >
+        {content}
+      </Pressable>
+    );
+  }
+
+  return <View style={containerStyle}>{content}</View>;
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: DS_SPACING[200],
+    // Fixed height so a tall leading node doesn't grow the pill past an icon+label one.
+    // Horizontal padding is applied per-instance (equal to the vertical breathing room): normal pills
+    // use 12, badge pills 8; icon-only pills get a fixed width instead (see `iconOnly` below).
+    height: DS_SPACING[2000],
+    borderRadius: DS_RADIUS.round,
+  },
+  // Fixed width equal to `container`'s own fixed height — a true circle regardless of the leading
+  // icon's size, rather than letting width emerge from padding + icon width (see the containerStyle
+  // comment above).
+  iconOnly: {
+    width: DS_SPACING[2000],
+  },
+  selected: {
+    // surface.inverse, not text.regular — this is a dark panel FILL, not ink; the two tokens share a
+    // value today but must be free to diverge in a rebrand.
+    backgroundColor: DS_SEMANTIC.surface.inverse,
+    // Transparent border matching not_selected's 2px, so both variants have identical layout boxes
+    // (otherwise unselected pills render taller and the row looks uneven). Reserved at the focus
+    // ring's own width (not 1px) so focusing only swaps the border colour, never its width — a
+    // width change on focus would otherwise shift the pill's layout, same fix as Button's border.
+    borderWidth: 2,
+    borderColor: 'transparent',
+  },
+  notSelected: {
+    backgroundColor: DS_SEMANTIC.surface.white,
+    // No border — the resting shadow alone separates the pill from the surface. Keep a transparent
+    // border (matching selected's reserved focus-ring width) so the box matches its height.
+    borderWidth: 2,
+    borderColor: 'transparent',
+    ...DS_SHADOW.resting,
+  },
+  pressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  focused: {
+    borderColor: DS_SEMANTIC.interaction.focused,
+  },
+  // Dims the WHOLE pill — container opacity multiplies down through every child in RN, so the
+  // label/icon dim with it; there is no way for a child to opt back out of an ancestor's opacity.
+  disabled: {
+    opacity: DS_SEMANTIC.interaction.disabledOpacity,
+  },
+  // Sizes to its content so the leading slot can hold an icon of any size or a custom node.
+  iconSlot: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  // No pinned lineHeight — the pill's height follows the label typography (padding + natural line
+  // height), so a type-scale change resizes the pill instead of rattling inside a fixed box.
+  label: {
+    ...DS_TYPOGRAPHY.labelSm,
+  },
+});

package/starter-kit/components/Pill/Pill.types.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+/** Selection state of the pill. */
+export type PillVariant = 'selected' | 'not_selected';
+
+export interface PillProps {
+  /** Chip text. */
+  label?: string;
+  /** Selection state. */
+  variant?: PillVariant;
+  /** Screen-reader name. Strongly recommended for an icon-only pill (`showText={false}`) — it is not
+   *  enforced, so omitting it means the placeholder `label` default gets announced instead. Defaults
+   *  to `label` for text pills. */
+  accessibilityLabel?: string;
+  /** Hide the label for an icon-only pill. */
+  showText?: boolean;
+  /** Renders in the inverse/regular color based on selection (preferred over `icon`). */
+  iconName?: IconName;
+  /** Render size for `iconName` (default 16). */
+  iconSize?: number;
+  /** Custom leading node — sizes naturally; takes precedence over the default menu icon. */
+  icon?: ReactNode;
+  /** Tap handler. */
+  onPress?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Pill/index.ts

@@ -0,0 +1,2 @@
+export { Pill } from './Pill';
+export type { PillProps, PillVariant } from './Pill.types';

package/starter-kit/components/PillRow/PillRow.catalog.tsx

@@ -0,0 +1,91 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { PillRow } from './PillRow';
+
+export default defineCatalogPage({
+  component: 'PillRow',
+  group: 'Actions',
+  description: 'A horizontally-scrolling row of Pill chips, with an optional trailing icon-only add pill — keeps the selected pill scrolled into view automatically.',
+  whenToUse: 'A scrollable row of selection chips (e.g. saved-place shortcuts) — for a fixed row of action buttons instead, use ButtonGroup.',
+  a11y: 'The row itself carries no accessibility role; each Pill (including the add pill) keeps its own accessibilityLabel/role from the Pill component.',
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'few',
+        name: 'Few pills',
+        node: (
+          <PillRow
+            pills={[
+              { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+      {
+        key: 'many',
+        name: 'Many pills (scrollable)',
+        node: (
+          <PillRow
+            pills={[
+              { id: 'home', label: 'Home', variant: 'not_selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'selected', iconName: 'briefcase' },
+              { id: 'gym', label: 'Gym', variant: 'not_selected', iconName: 'map' },
+              { id: 'saved', label: 'Saved', variant: 'not_selected', iconName: 'bell' },
+              { id: 'nearby', label: 'Nearby', variant: 'not_selected', iconName: 'pin' },
+              { id: 'recent', label: 'Recent', variant: 'not_selected', iconName: 'clock' },
+            ]}
+          />
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'no-add',
+        name: 'No add pill',
+        props: { showAddPill: false },
+        node: (
+          <PillRow
+            showAddPill={false}
+            pills={[
+              { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+      {
+        key: 'add-selected',
+        name: 'Add pill selected',
+        props: { addSelected: true },
+        node: (
+          <PillRow
+            addSelected
+            pills={[
+              { id: 'home', label: 'Home', variant: 'not_selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+      {
+        key: 'min-width',
+        name: 'Minimum pill width',
+        props: { minPillWidth: 96 },
+        node: (
+          <PillRow
+            minPillWidth={96}
+            pills={[
+              { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/PillRow/PillRow.tsx

@@ -0,0 +1,140 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { ScrollView, View, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { DS_SPACING } from '../../tokens';
+import { Pill } from '../Pill';
+import type { PillRowItem, PillRowProps } from './PillRow.types';
+
+const GAP = DS_SPACING[600];
+
+const DEFAULT_PILLS: NonNullable<PillRowProps['pills']> = [
+  { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+  { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+];
+
+/**
+ * A horizontally-scrolling row of Pills with an optional trailing icon-only add pill. Keeps the
+ * selected pill scrolled into view, and resets to the start when the pill set genuinely changes.
+ */
+export function PillRow({
+  pills: pillsProp,
+  showAddPill = true,
+  minPillWidth = 0,
+  onAddPress,
+  addSelected = false,
+  style,
+  trailing,
+}: PillRowProps) {
+  const pills = pillsProp ?? DEFAULT_PILLS;
+  const idsKey = pills.map(p => p.id).join('|');
+
+  const scrollRef = useRef<ScrollView>(null);
+  const scrollXRef = useRef(0);
+  // Laid-out position of each pill (x within the scroll content + width), kept for scroll-into-view.
+  const posRef = useRef<Map<string, { x: number; width: number }>>(new Map());
+  const [viewportW, setViewportW] = useState(0);
+
+  const onPillLayout = (id: string, e: LayoutChangeEvent) => {
+    const { x, width } = e.nativeEvent.layout;
+    posRef.current.set(id, { x, width });
+  };
+
+  // A genuinely different set of pills (not just a selection change within the same set) forgets
+  // wherever the row was scrolled to and starts back at the beginning — otherwise a stale scroll
+  // offset or a stale cached position from the PREVIOUS pill set could carry over onto this one.
+  useEffect(() => {
+    posRef.current.clear();
+    scrollRef.current?.scrollTo({ x: 0, animated: false });
+  }, [idsKey]);
+
+  // Keep the selected pill fully in view. The selected pill is the one with variant 'selected', or the
+  // add pill (tracked under '__add__') when it's selected. Re-runs whenever the selection or the layout
+  // changes; deferred a frame so positions are fresh after a layout change.
+  const selectedId = useMemo(
+    () => (addSelected ? '__add__' : pills.find(p => p.variant === 'selected')?.id),
+    [addSelected, pills],
+  );
+  useEffect(() => {
+    if (!selectedId || viewportW <= 0) return;
+    const raf = requestAnimationFrame(() => {
+      const pos = posRef.current.get(selectedId);
+      if (!pos) return;
+      const left = scrollXRef.current;
+      const right = left + viewportW;
+      if (pos.x < left) {
+        scrollRef.current?.scrollTo({ x: Math.max(0, pos.x - GAP), animated: true });
+      } else if (pos.x + pos.width > right) {
+        scrollRef.current?.scrollTo({ x: pos.x + pos.width - viewportW + GAP, animated: true });
+      }
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [selectedId, viewportW, idsKey]);
+
+  // `minPillWidth` is applied as a floor (`minWidth`) so each pill grows to fit its own label (never
+  // truncates) while short labels still hold the minimum.
+  const pillStyle = minPillWidth > 0 ? { minWidth: minPillWidth } : undefined;
+
+  const renderPill = (pill: PillRowItem) => (
+    <View key={pill.id} onLayout={e => onPillLayout(pill.id, e)}>
+      <Pill
+        label={pill.label}
+        variant={pill.variant}
+        showText={pill.showText}
+        iconName={pill.iconName}
+        iconSize={pill.iconSize}
+        icon={pill.icon}
+        onPress={pill.onPress}
+        disabled={pill.disabled}
+        loading={pill.loading}
+        accessibilityLabel={pill.accessibilityLabel}
+        style={pillStyle}
+      />
+    </View>
+  );
+
+  return (
+    <ScrollView
+      ref={scrollRef}
+      horizontal
+      showsHorizontalScrollIndicator={false}
+      // `style` (the ScrollView's OWN box, not its scrollable content) needs an explicit bound —
+      // without it, react-native-web sizes the scroll viewport to hug its content instead of the
+      // width its parent actually gives it, so it never overflows and never becomes swipable at
+      // all (a wide pill set just spills past the layout silently). `contentContainerStyle` is a
+      // separate thing: the inner row that's *allowed* to be wider than the viewport.
+      style={styles.scrollView}
+      contentContainerStyle={[styles.row, style]}
+      onLayout={e => setViewportW(e.nativeEvent.layout.width)}
+      onScroll={e => {
+        scrollXRef.current = e.nativeEvent.contentOffset.x;
+      }}
+      scrollEventThrottle={16}
+    >
+      {pills.map(renderPill)}
+      {showAddPill && (
+        // Record the add pill's position (under '__add__') so it can be scrolled into view when
+        // selected — tracked separately from `pills` since it's rendered outside that list.
+        <View onLayout={e => onPillLayout('__add__', e)}>
+          <Pill
+            variant={addSelected ? 'selected' : 'not_selected'}
+            showText={false}
+            iconName="pencil"
+            accessibilityLabel="Edit"
+            onPress={onAddPress}
+          />
+        </View>
+      )}
+      {trailing}
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  scrollView: { width: '100%' },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[600],
+    minHeight: DS_SPACING[2400],
+    paddingVertical: DS_SPACING[200],
+  },
+});

package/starter-kit/components/PillRow/PillRow.types.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { PillProps } from '../Pill';
+
+export interface PillRowItem extends Omit<PillProps, 'style'> {
+  id: string;
+}
+
+export interface PillRowProps {
+  /** Pills to render — each is a Pill's own props plus an id. Defaults to a two-item Home/Work
+   *  sample. */
+  pills?: PillRowItem[];
+  /** Icon-only add/edit pill at the end of the row. */
+  showAddPill?: boolean;
+  /** Floor for the content pills' width (px). Excludes the icon-only add pill so it stays circular. */
+  minPillWidth?: number;
+  /** Tap handler for the add pill. */
+  onAddPress?: () => void;
+  /** Render the add pill in the selected state. */
+  addSelected?: boolean;
+  style?: StyleProp<ViewStyle>;
+  /** Custom trailing content instead of the add pill. */
+  trailing?: ReactNode;
+}

package/starter-kit/components/PillRow/index.ts

@@ -0,0 +1,2 @@
+export { PillRow } from './PillRow';
+export type { PillRowProps, PillRowItem } from './PillRow.types';

package/starter-kit/components/ProgressDots/ProgressDots.catalog.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { ProgressDots } from './ProgressDots';
+
+export default defineCatalogPage({
+  component: 'ProgressDots',
+  group: 'Feedback',
+  description: 'A row of dots for a stepped flow; the active dot widens into a pill.',
+  a11y: 'Decorative progress indicator; convey the "step X of Y" position in text for screen readers.',
+  // No `variant` prop exists on ProgressDots — its "Variants" column just shows the one default
+  // look; `active`'s different positions are progress states, covered under "States".
+  variants: {
+    items: [{ key: 'default', name: 'Default', node: <ProgressDots active={1} total={4} /> }],
+  },
+  states: {
+    items: [
+      { key: 'first', name: 'First step', node: <ProgressDots active={0} total={4} /> },
+      { key: 'middle', name: 'Middle step', node: <ProgressDots active={2} total={4} /> },
+      { key: 'last', name: 'Last step', node: <ProgressDots active={3} total={4} /> },
+    ],
+  },
+});

package/starter-kit/components/ProgressDots/ProgressDots.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING } from '../../tokens';
+
+export interface ProgressDotsProps {
+  /** 0-based index of the current step. The active dot widens into a pill. */
+  active: number;
+  /** Total number of steps (dots). */
+  total?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Step progress indicator — a row of dots where the current step is a widened pill.
+ */
+export function ProgressDots({ active, total = 6, style }: ProgressDotsProps) {
+  return (
+    <View
+      style={[styles.row, style]}
+      accessible
+      accessibilityRole="progressbar"
+      accessibilityLabel={`Step ${active + 1} of ${total}`}
+      accessibilityValue={{ min: 1, max: total, now: active + 1 }}
+    >
+      {Array.from({ length: total }).map((_, i) => (
+        <View key={i} style={[styles.dot, i === active && styles.dotActive]} />
+      ))}
+    </View>
+  );
+}
+
+// 7px is intentionally smaller than DS_SPACING[400]=8px — optical correction for small dots.
+const DOT_H = 7;
+const DOT_PILL_W = 20;
+const DOT_RADIUS = 4;
+
+const styles = StyleSheet.create({
+  row: { flexDirection: 'row', justifyContent: 'center', alignItems: 'center', gap: DS_SPACING[200] },
+  dot: { width: DOT_H, height: DOT_H, borderRadius: DOT_RADIUS, backgroundColor: DS_SEMANTIC.border.subtle },
+  // surface.inverse, not text.regular — a dark FILL, not ink (same reasoning as Pill/Toast).
+  dotActive: { width: DOT_PILL_W, borderRadius: DOT_RADIUS, backgroundColor: DS_SEMANTIC.surface.inverse },
+});

package/starter-kit/components/ProgressDots/index.ts

@@ -0,0 +1,2 @@
+export { ProgressDots } from './ProgressDots';
+export type { ProgressDotsProps } from './ProgressDots';

package/starter-kit/components/Radio/Radio.catalog.tsx

@@ -0,0 +1,38 @@
+import React, { useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Radio } from './Radio';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  radioGroup: { gap: DS_SPACING[600], alignItems: 'flex-start' },
+});
+
+function RadioGroupDemo() {
+  const [value, setValue] = useState('uptown');
+  return (
+    <View style={styles.radioGroup}>
+      <Radio selected={value === 'uptown'} onPress={() => setValue('uptown')} label="Uptown & The Bronx" />
+      <Radio selected={value === 'downtown'} onPress={() => setValue('downtown')} label="Downtown & Brooklyn" />
+    </View>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'Radio',
+  group: 'Controls',
+  specimenSize: 'compact',
+  description: 'A single circular selection control — a filled dot appears in the ring when selected. A group of mutually-exclusive Radios is just multiple instances sharing one selected value in the consumer.',
+  whenToUse: 'One selection from a mutually-exclusive set — checking one should un-check another. For an independent on/off fact, use Checkbox; for a setting that takes effect immediately, use Switch.',
+  a11y: 'Renders a Pressable with accessibilityRole="radio" and accessibilityState.selected; the optional label doubles as its accessibilityLabel.',
+  variants: {
+    items: [{ key: 'default', name: 'Default (tap to select)', node: <RadioGroupDemo /> }],
+  },
+  states: {
+    items: [
+      { key: 'unselected', name: 'Unselected', node: <Radio selected={false} onPress={() => {}} label="Uptown & The Bronx" /> },
+      { key: 'selected', name: 'Selected', node: <Radio selected={true} onPress={() => {}} label="Uptown & The Bronx" /> },
+      { key: 'disabled', name: 'Disabled', node: <Radio selected={true} onPress={() => {}} disabled label="Uptown & The Bronx" /> },
+    ],
+  },
+});