@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

@@ -0,0 +1,89 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Avatar } from '../Avatar';
+import { Badge } from '../Badge';
+import { Button } from '../Button';
+import { ListItem } from './ListItem';
+import { Icon } from '../../icons/Icon.native';
+import { DS_SEMANTIC } from '../../tokens';
+
+export default defineCatalogPage({
+  component: 'ListItem',
+  group: 'Layout',
+  description: 'A single row: optional leading/trailing slots flanking a title (+ optional subtitle/footer). Stack several inside a List for a settings screen, menu, or search-results list.',
+  whenToUse: "A row in a set of visually-light peers sharing a List's own surface and dividers. For a standalone unit with its own shadow, use Card instead.",
+  a11y: 'A tappable row (onPress set) renders as a Pressable with accessibilityRole="button" and an accessibilityLabel built from title + subtitle; a plain row is a non-interactive View.',
+  // No `variant` prop exists on ListItem — its "Variants" column shows the title-only default and
+  // the title+subtitle look; slot/interaction configurations live under "States".
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'default', name: 'Default', node: <ListItem title="Notifications" /> },
+      { key: 'subtitle', name: 'With subtitle', node: <ListItem title="Notifications" subtitle="Delay and service alerts" /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'leading',
+        name: 'With leading',
+        node: <ListItem title="Jordan Lee" subtitle="Last trip: Uptown & The Bronx" leading={<Avatar initials="JL" size={32} />} />,
+      },
+      {
+        key: 'trailing',
+        name: 'With trailing',
+        node: <ListItem title="Notifications" trailing={<Icon name="chevron-right" color={DS_SEMANTIC.text.muted} />} />,
+      },
+      {
+        key: 'footer-text',
+        name: 'With footer (text)',
+        node: <ListItem title="Signal delay" subtitle="Reported near 14 St" footer="2 min ago" />,
+      },
+      {
+        key: 'footer-badge',
+        name: 'With footer (badge)',
+        node: <ListItem title="Line suspended" subtitle="96 St and 137 St" footer={<Badge variant="negative" label="Service alert" />} />,
+      },
+      {
+        key: 'footer-button',
+        name: 'With footer (button)',
+        node: <ListItem title="Trip request" subtitle="Jordan Lee wants to share a ride" footer={<Button label="Accept" size="small" onPress={() => {}} />} />,
+      },
+      {
+        key: 'trailing-text',
+        name: 'With trailing data',
+        node: (
+          <ListItem
+            title="Language"
+            trailingText="English"
+            trailing={<Icon name="chevron-right" color={DS_SEMANTIC.text.muted} />}
+            onPress={() => {}}
+          />
+        ),
+      },
+      {
+        key: 'trailing-subtext',
+        name: 'With trailing data (secondary)',
+        node: <ListItem title="Storage used" trailingText="2.4 GB" trailingSubtext="of 5 GB" />,
+      },
+      {
+        key: 'trailing-button',
+        name: 'With trailing button',
+        node: <ListItem title="Pending invite" subtitle="Sam Rivera" trailing={<Button label="Accept" size="small" onPress={() => {}} />} />,
+      },
+      {
+        key: 'pressable',
+        name: 'Pressable',
+        node: (
+          <ListItem
+            title="Notifications"
+            trailing={<Icon name="chevron-right" color={DS_SEMANTIC.text.muted} />}
+            onPress={() => {}}
+          />
+        ),
+      },
+      { key: 'disabled', name: 'Disabled', node: <ListItem title="Notifications" onPress={() => {}} disabled /> },
+    ],
+  },
+});

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

@@ -0,0 +1,165 @@
+import React, { useState, type ReactNode } from 'react';
+import { View, Text, Pressable, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+
+export interface ListItemProps {
+  /** Primary text. */
+  title: string;
+  /** Small secondary line below the title. */
+  subtitle?: string;
+  /** A third block below subtitle — for lower-priority extra content (a timestamp, a count, or a
+   *  Badge/Button) that shouldn't compete with subtitle for attention. A plain string renders in the
+   *  same small muted style as before; pass a Badge/Button/other node directly for anything richer. */
+  footer?: ReactNode;
+  /** Leading slot — typically an Avatar or Icon. */
+  leading?: ReactNode;
+  /** Compact right-aligned value shown before the trailing slot — e.g. a settings row's current
+   *  value ("English") ahead of its chevron. */
+  trailingText?: string;
+  /** A second, more muted right-aligned line below `trailingText` — e.g. a unit or a status caption
+   *  under the primary value. Only meaningful alongside `trailingText`. */
+  trailingSubtext?: string;
+  /** Trailing slot — typically a chevron Icon, a Switch, a Button, or a value label. */
+  trailing?: ReactNode;
+  /** Makes the whole row tappable. */
+  onPress?: () => void;
+  /** Non-interactive, dimmed. */
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** A single row: optional leading/trailing slots flanking a title (+ optional subtitle/footer).
+ *  Stack several inside a {@link List} for a settings screen, menu, or search-results list. */
+export function ListItem({
+  title,
+  subtitle,
+  footer,
+  leading,
+  trailingText,
+  trailingSubtext,
+  trailing,
+  onPress,
+  disabled = false,
+  style,
+}: ListItemProps) {
+  const [focused, setFocused] = useState(false);
+  const inner = (
+    <>
+      {leading && <View style={styles.slot}>{leading}</View>}
+      <View style={styles.textGroup}>
+        <Text style={[styles.title, disabled && styles.disabledText]} numberOfLines={1}>{title}</Text>
+        {!!subtitle && (
+          <Text style={[styles.subtitle, disabled && styles.disabledText]} numberOfLines={1}>{subtitle}</Text>
+        )}
+        {footer != null &&
+          (typeof footer === 'string' ? (
+            <Text style={[styles.footerText, disabled && styles.disabledText]} numberOfLines={1}>{footer}</Text>
+          ) : (
+            <View style={styles.footerNode}>{footer}</View>
+          ))}
+      </View>
+      {(trailingText || trailing) && (
+        <View style={styles.trailingGroup}>
+          {!!trailingText && (
+            <View style={styles.trailingTextGroup}>
+              <Text style={[styles.trailingText, disabled && styles.disabledText]} numberOfLines={1}>{trailingText}</Text>
+              {!!trailingSubtext && (
+                <Text style={[styles.trailingSubtext, disabled && styles.disabledText]} numberOfLines={1}>{trailingSubtext}</Text>
+              )}
+            </View>
+          )}
+          {trailing && <View style={styles.slot}>{trailing}</View>}
+        </View>
+      )}
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        onPress={disabled ? undefined : onPress}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        disabled={disabled}
+        accessibilityRole="button"
+        accessibilityLabel={[title, subtitle].filter(Boolean).join(', ')}
+        accessibilityState={{ disabled }}
+        // Keyboard focus shows the same highlight as a press — a full-width row has no border to
+        // recolor, so focus mirrors the pressed treatment (same policy as SegmentedToggle/UnderlineTabs).
+        style={({ pressed }) => [styles.row, (pressed || focused) && !disabled && styles.pressed, style]}
+      >
+        {inner}
+      </Pressable>
+    );
+  }
+
+  return <View style={[styles.row, style]}>{inner}</View>;
+}
+
+const styles = StyleSheet.create({
+  row: {
+    width: '100%',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[600],
+    minHeight: DS_A11Y_MIN_TOUCH_TARGET,
+    paddingVertical: DS_SPACING[800],
+    paddingHorizontal: DS_SPACING[400],
+    backgroundColor: DS_SEMANTIC.surface.white,
+  },
+  pressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  slot: {
+    flexShrink: 0,
+  },
+  textGroup: {
+    flex: 1,
+    minWidth: 0,
+    gap: DS_SPACING[100],
+  },
+  title: {
+    ...DS_TYPOGRAPHY.bodyMd,
+    color: DS_SEMANTIC.text.regular,
+  },
+  subtitle: {
+    ...DS_TYPOGRAPHY.bodyXs,
+    color: DS_SEMANTIC.text.muted,
+  },
+  footerText: {
+    ...DS_TYPOGRAPHY.labelXs,
+    color: DS_SEMANTIC.text.muted,
+  },
+  // A node footer (Badge/Button) brings its own sizing/color — just a top nudge so it doesn't sit
+  // flush against subtitle.
+  footerNode: {
+    marginTop: DS_SPACING[100],
+    alignItems: 'flex-start',
+  },
+  trailingGroup: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[300],
+    flexShrink: 0,
+  },
+  trailingTextGroup: {
+    alignItems: 'flex-end',
+    gap: DS_SPACING[100],
+  },
+  trailingText: {
+    ...DS_TYPOGRAPHY.bodySm,
+    color: DS_SEMANTIC.text.muted,
+    flexShrink: 1,
+  },
+  trailingSubtext: {
+    ...DS_TYPOGRAPHY.labelXs,
+    color: DS_SEMANTIC.text.muted,
+    flexShrink: 1,
+  },
+  // Disabled text — a step lighter than `text.muted` (which the subtitle/footer already use for
+  // ordinary secondary text), so a disabled row reads as inactive rather than just secondary —
+  // same reasoning as InputField/SearchField (see DS_SEMANTIC.text.disabled's own doc comment).
+  disabledText: {
+    color: DS_SEMANTIC.text.disabled,
+  },
+});

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

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

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

@@ -0,0 +1,34 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Loading } from './Loading';
+import { DS_SEMANTIC } from '../../tokens';
+
+export default defineCatalogPage({
+  component: 'Loading',
+  group: 'Feedback',
+  description: 'An indeterminate loader — the shape fills up, empties out, then fills again, seamlessly. Two variants: circle (used internally by Button and Pill for their own loading states) and linear.',
+  a11y: 'Exposed to assistive tech as accessibilityRole="progressbar" with accessibilityLabel="Loading" — no extra wiring needed at the call site.',
+  // One example per `variant` enum value — `circle` is the default, so it comes first.
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'circle', name: 'Circle', props: { variant: 'circle' }, node: <Loading variant="circle" /> },
+      { key: 'linear', name: 'Linear', props: { variant: 'linear' }, node: <Loading variant="linear" /> },
+    ],
+  },
+  // `size` (circle) and `height` (linear) are continuous numbers, not enums — small/medium/large
+  // and thin/default/thick are explicit, labeled sweeps across each. Each sweep names its variant
+  // through `group`, so the page shows one row per variant; Accent colour applies to both and
+  // stays in "Other configurations".
+  states: {
+    items: [
+      { key: 'small-circle', group: 'circle', name: 'Small circle', node: <Loading variant="circle" size={14} /> },
+      { key: 'medium-circle', group: 'circle', name: 'Medium circle (default)', node: <Loading variant="circle" size={20} /> },
+      { key: 'large-circle', group: 'circle', name: 'Large circle', node: <Loading variant="circle" size={40} /> },
+      { key: 'thin-linear', group: 'linear', fill: true, name: 'Thin linear', node: <Loading variant="linear" height={2} /> },
+      { key: 'default-linear', group: 'linear', fill: true, name: 'Default linear', node: <Loading variant="linear" height={4} /> },
+      { key: 'thick-linear', group: 'linear', fill: true, name: 'Thick linear', node: <Loading variant="linear" height={8} /> },
+      { key: 'accent', name: 'Accent colour', node: <Loading variant="circle" color={DS_SEMANTIC.emphasis.info} /> },
+    ],
+  },
+});

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

@@ -0,0 +1,121 @@
+import React, { useEffect, useRef } from 'react';
+import { View, Animated, Easing, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import Svg, { Path, type PathProps } from 'react-native-svg';
+import { DS_SEMANTIC, DS_MOTION_LOOP_DURATION } from '../../tokens';
+
+// `Animated.createAnimatedComponent` forces `collapsable: false` onto the wrapped component's
+// props (so the native view isn't flattened out from under the native driver) — react-native-svg's
+// web shim doesn't recognize `collapsable` and passes it straight through to the DOM, so an
+// animated Path would otherwise log "Received `false` for a non-boolean attribute `collapsable`."
+// This wrapper drops it before it reaches the real Path; native platforms never read it off Path.
+const AnimatedPath = Animated.createAnimatedComponent(
+  React.forwardRef<unknown, PathProps & { collapsable?: boolean }>(({ collapsable: _collapsable, ...rest }, ref) => (
+    <Path ref={ref as never} {...rest} />
+  )),
+);
+
+// A 20×20 viewBox, ~292° arc (radius 9, centre 10,10), 2px stroke. The arc is a single stroke whose
+// dash exactly covers its length, so animating the dash offset draws it on (fills) then off (empties).
+const ARC_PATH =
+  'M19 10C19 11.9289 18.3803 13.8067 17.2323 15.3567C16.0843 16.9067 14.4687 18.0468 12.6236 18.6091C10.7785 19.1714 8.8016 19.126 6.98426 18.4797C5.16692 17.8334 3.6053 16.6203 2.52959 15.0193C1.45388 13.4182 0.920996 11.514 1.00948 9.58714C1.09796 7.66032 1.80313 5.81291 3.02105 4.3172C4.23897 2.8215 5.9052 1.75664 7.77412 1.2796C9.64305 0.802556 11.6158 0.938564 13.4016 1.66758';
+const ARC_LEN = 45.9;
+
+export type LoadingVariant = 'circle' | 'linear';
+
+export interface LoadingProps {
+  /** Which shape to render. @default 'circle' */
+  variant?: LoadingVariant;
+  /** Diameter in px — circle only. @default 20 */
+  size?: number;
+  /** Track width — linear only. @default '100%' */
+  width?: number | `${number}%`;
+  /** Track/bar thickness — linear only. @default 4 */
+  height?: number;
+  /** Stroke (circle) / fill (linear) colour. Defaults to the regular text colour. */
+  color?: string;
+  /** Track (background) colour — linear only. */
+  trackColor?: string;
+  /** One fill→empty cycle duration in ms. @default DS_MOTION_LOOP_DURATION.spinner (1200) */
+  duration?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Indeterminate loader — the shape fills up, empties out, then fills again, seamlessly, in either of
+ * two variants:
+ *  - `circle` (default): a dash slides across the arc's own length over a 2× period, so a single
+ *    continuous timing produces the fill→empty→fill motion.
+ *  - `linear`: a bar's width animates 0→100%→0% explicitly (two phases — there's no dash-slide
+ *    equivalent for a plain width fill).
+ * Both are JS-driven (`useNativeDriver: false`), so Fabric-safe: a continuous loop on an
+ * always-mounted view, no imperative setValue. Used internally by Button and Pill for their own
+ * loading states (circle).
+ */
+export function Loading({
+  variant = 'circle',
+  size = 20,
+  width = '100%',
+  height = 4,
+  color = DS_SEMANTIC.text.regular,
+  trackColor = DS_SEMANTIC.surface.muted,
+  duration = DS_MOTION_LOOP_DURATION.spinner,
+  style,
+}: LoadingProps) {
+  // Circle drives this directly as a dash offset (ARC_LEN..-ARC_LEN); linear reads it as 0..1 and
+  // interpolates to a width percentage. Different ranges, same underlying value — each variant's own
+  // effect below sets up the animation appropriate to it.
+  const progress = useRef(new Animated.Value(variant === 'circle' ? ARC_LEN : 0)).current;
+
+  useEffect(() => {
+    const loop =
+      variant === 'circle'
+        ? Animated.loop(
+            Animated.timing(progress, {
+              toValue: -ARC_LEN,
+              duration,
+              easing: Easing.inOut(Easing.ease),
+              useNativeDriver: false,
+            }),
+          )
+        : Animated.loop(
+            Animated.sequence([
+              Animated.timing(progress, { toValue: 1, duration, easing: Easing.inOut(Easing.ease), useNativeDriver: false }),
+              Animated.timing(progress, { toValue: 0, duration, easing: Easing.inOut(Easing.ease), useNativeDriver: false }),
+            ]),
+          );
+    loop.start();
+    return () => loop.stop();
+  }, [variant, duration, progress]);
+
+  if (variant === 'linear') {
+    const fillWidth = progress.interpolate({ inputRange: [0, 1], outputRange: ['0%', '100%'] });
+    return (
+      <View
+        style={[styles.track, { width, height, backgroundColor: trackColor, borderRadius: height / 2 }, style]}
+        accessible
+        accessibilityRole="progressbar"
+        accessibilityLabel="Loading"
+      >
+        <Animated.View
+          style={[styles.fill, { height, backgroundColor: color, width: fillWidth, borderRadius: height / 2 }]}
+        />
+      </View>
+    );
+  }
+
+  return (
+    // The accessibility props live on this wrapping View, not the Svg: react-native-svg's web shim
+    // forwards unrecognized props straight to the DOM, and `accessible`/`accessibilityRole` would
+    // otherwise log "Received `true`/`\"progressbar\"` for a non-boolean/non-standard attribute."
+    <View style={style} accessible accessibilityRole="progressbar" accessibilityLabel="Loading">
+      <Svg width={size} height={size} viewBox="0 0 20 20" fill="none">
+        <AnimatedPath d={ARC_PATH} stroke={color} strokeWidth={2} strokeDasharray={ARC_LEN} strokeDashoffset={progress} />
+      </Svg>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  track: { overflow: 'hidden' },
+  fill: { position: 'absolute', left: 0, top: 0 },
+});

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

@@ -0,0 +1,2 @@
+export { Loading } from './Loading';
+export type { LoadingProps, LoadingVariant } from './Loading';

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

@@ -0,0 +1,93 @@
+import React from 'react';
+import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { Pill } from './Pill';
+
+// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
+// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
+// cannot combine.
+function grid(
+  rowLabel: string,
+  columnLabel: string,
+  rows: { key: string; label: string }[],
+  columns: { key: string; label: string }[],
+  cell: (row: string, column: string) => React.ReactNode,
+  size?: ComparisonDef['size'],
+): ComparisonDef {
+  return {
+    rowLabel,
+    columnLabel,
+    rows,
+    columns,
+    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+    size,
+  };
+}
+
+// Pill: Selection × State.
+const PILL_COMPARISON = grid(
+  'Selection',
+  'State',
+  [
+    { key: 'selected', label: 'Selected' },
+    { key: 'not-selected', label: 'Not selected' },
+  ],
+  [
+    { key: 'icon-text', label: 'Icon + Text' },
+    { key: 'icon-only', label: 'Icon-only' },
+    { key: 'disabled', label: 'Disabled' },
+    { key: 'loading', label: 'Loading' },
+  ],
+  (row, column) => (
+    <Pill
+      label="Home"
+      variant={row === 'selected' ? 'selected' : 'not_selected'}
+      iconName="home"
+      showText={column !== 'icon-only'}
+      accessibilityLabel="Home"
+      disabled={column === 'disabled'}
+      loading={column === 'loading'}
+      onPress={() => {}}
+    />
+  ),
+  'compact',
+);
+
+export default defineCatalogPage({
+  component: 'Pill',
+  group: 'Actions',
+  specimenSize: 'compact',
+  comparison: PILL_COMPARISON,
+  description: 'A compact selectable chip — selected/unselected states with an optional leading icon.',
+  whenToUse: "A selection toggle, not an action — tapping it flips a persistent selected state. If tapping it should instead make something happen, use Button.",
+  a11y: 'Pressable with accessibilityLabel; an icon-only pill (showText={false}) needs an explicit accessibilityLabel so it is announced.',
+  variants: {
+    items: [
+      { key: 'selected', name: 'Selected', props: { variant: 'selected' }, node: <Pill label="Home" variant="selected" iconName="home" onPress={() => {}} /> },
+      { key: 'not-selected', name: 'Not selected', props: { variant: 'not_selected' }, node: <Pill label="Work" variant="not_selected" iconName="briefcase" onPress={() => {}} /> },
+    ],
+  },
+  states: {
+    items: [
+      {
+        key: 'icon-text',
+        name: 'Icon + Text',
+        node: <Pill label="Nearby" variant="not_selected" iconName="pin" onPress={() => {}} />,
+      },
+      {
+        key: 'icon-only',
+        name: 'Icon-only',
+        node: <Pill label="Saved" variant="not_selected" iconName="bell" showText={false} onPress={() => {}} />,
+      },
+      {
+        key: 'disabled',
+        name: 'Disabled',
+        node: <Pill label="Sold out" variant="not_selected" iconName="clock" disabled onPress={() => {}} />,
+      },
+      {
+        key: 'loading',
+        name: 'Loading',
+        node: <Pill label="Saving" variant="not_selected" iconName="clock" loading onPress={() => {}} />,
+      },
+    ],
+  },
+});