@krapwoo/ds-viewer 0.1.1 → 0.3.0

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

@@ -0,0 +1,67 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { EmptyState } from './EmptyState';
+import { DS_SEMANTIC } from '../../tokens';
+
+export default defineCatalogPage({
+  component: 'EmptyState',
+  group: 'Layout',
+  description: 'A centred placeholder for a screen or section with nothing to show yet — no results, no saved items, a first-run state.',
+  whenToUse: "Fills the entire content area because there's nothing else to show. For a note that sits alongside other real content, use Banner instead.",
+  a11y: 'A plain View with text; the action(s) render as real Buttons inside a ButtonGroup, which carry their own accessibility.',
+  // No `variant` prop exists on EmptyState — its "Variants" column shows the minimal default
+  // (iconName omitted, so it falls back to the real default) — the description/action
+  // configurations live under "States".
+  variants: {
+    itemsFill: true,
+    items: [{ key: 'default', name: 'Default', node: <EmptyState title="No saved trips yet" /> }],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'description',
+        name: 'With description',
+        node: <EmptyState iconName="search" title="No results found" description="Try a different station or address." />,
+      },
+      {
+        key: 'action',
+        name: 'With action',
+        node: (
+          <EmptyState
+            iconName="waypoints"
+            title="No saved trips yet"
+            description="Your saved trips will show up here."
+            action={{ label: 'Start a trip', onPress: () => {} }}
+          />
+        ),
+      },
+      {
+        key: 'secondary-action',
+        name: 'With two actions',
+        props: { secondaryAction: true },
+        node: (
+          <EmptyState
+            iconName="waypoints"
+            title="No saved trips yet"
+            description="Your saved trips will show up here."
+            action={{ label: 'Start a trip', onPress: () => {} }}
+            secondaryAction={{ label: 'Not now', onPress: () => {} }}
+          />
+        ),
+      },
+      {
+        key: 'custom-color',
+        name: 'Custom avatar colour',
+        node: (
+          <EmptyState
+            iconName="triangle-alert"
+            title="Something went wrong"
+            description="Check your connection and try again."
+            backgroundColor={DS_SEMANTIC.emphasis.negative}
+          />
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,88 @@
+import React from 'react';
+import { View, Text, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { Avatar } from '../Avatar';
+import { Button } from '../Button';
+import { ButtonGroup } from '../ButtonGroup';
+import type { IconName } from '../../icons';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const AVATAR_SIZE = 64;
+
+export interface EmptyStateAction {
+  label: string;
+  onPress: () => void;
+}
+
+export interface EmptyStateProps {
+  /** Icon shown above the title, on an Avatar circle. Defaults to `users` — the same generic-person
+   *  glyph Avatar's own icon fallback uses, a reasonable default when nothing more specific fits
+   *  ("no saved trips", "no results"). Pass a more specific icon when one obviously fits. */
+  iconName?: IconName;
+  /** Override the avatar circle's fill — same prop, same meaning as Avatar's own `backgroundColor`.
+   *  Defaults to Avatar's own default (a neutral muted surface). */
+  backgroundColor?: string;
+  /** Primary message. */
+  title: string;
+  /** Supporting line below the title — what's empty, or what to do about it. */
+  description?: string;
+  /** Primary action rendered below the description (e.g. "Start a trip"). */
+  action?: EmptyStateAction;
+  /** Optional second action, stacked below `action` as a tertiary button (e.g. "Not now"). Only
+   *  rendered when `action` is also set — a secondary action with no primary one doesn't make sense. */
+  secondaryAction?: EmptyStateAction;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A centred placeholder for a screen or section with nothing to show yet — no results, no saved
+ * items, a first-run state. An Avatar (icon on a circular fill, not a bare icon — reuses the same
+ * component and default styling a real profile picture would use here), title, optional
+ * description, optional action(s), always in that order and always centred; for anything more
+ * custom (illustrations, more than two actions), compose your own layout instead of extending this
+ * one. `action`/`secondaryAction` render through `ButtonGroup`'s `vertical` layout — always `small`
+ * size (EmptyState's own actions read as a lighter-weight, secondary moment, never the primary CTA
+ * of the screen they sit in) — so the primary/tertiary pair already follows ButtonGroup's own
+ * composition rules (matching size, matching label-only configuration) with nothing extra to wire up.
+ */
+export function EmptyState({ iconName = 'users', backgroundColor, title, description, action, secondaryAction, style }: EmptyStateProps) {
+  return (
+    <View style={[styles.container, style]}>
+      <Avatar iconName={iconName} size={AVATAR_SIZE} backgroundColor={backgroundColor} />
+      <Text style={styles.title}>{title}</Text>
+      {!!description && <Text style={styles.description}>{description}</Text>}
+      {action && (
+        <ButtonGroup variant="vertical" style={styles.actionWrap}>
+          <Button label={action.label} onPress={action.onPress} size="small" />
+          {secondaryAction && <Button variant="tertiary" label={secondaryAction.label} onPress={secondaryAction.onPress} size="small" />}
+        </ButtonGroup>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    paddingHorizontal: DS_SPACING[1200],
+    paddingVertical: DS_SPACING[2000],
+    gap: DS_SPACING[400],
+  },
+  title: {
+    ...DS_TYPOGRAPHY.labelMd,
+    color: DS_SEMANTIC.text.regular,
+    textAlign: 'center',
+    marginTop: DS_SPACING[400],
+  },
+  description: {
+    ...DS_TYPOGRAPHY.bodySm,
+    color: DS_SEMANTIC.text.muted,
+    textAlign: 'center',
+  },
+  actionWrap: {
+    marginTop: DS_SPACING[400],
+    // Overrides ButtonGroup vertical's own default full-width stretch (right for Dock's button bar,
+    // wrong here) — EmptyState's actions read as a secondary, content-sized moment, not a bar
+    // spanning the whole width.
+    alignItems: 'center',
+  },
+});

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

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

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

@@ -0,0 +1,76 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { FieldContainer } from './FieldContainer';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  // FieldContainer — a stand-in "field" body, since the real component only supplies the chrome.
+  fieldContainerDemo: { height: 56, justifyContent: 'center', paddingHorizontal: DS_SPACING[800] },
+  fieldContainerText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.muted },
+});
+
+export default defineCatalogPage({
+  component: 'FieldContainer',
+  group: 'Sub-Parts',
+  description: 'The shared field chrome — white surface, medium radius, a 1px border that darkens on focus and mutes when disabled — behind InputField, TextArea, Dropdown, and SearchField, so all four share one visually-consistent field look instead of each re-implementing it.',
+  a11y: 'Renders a plain View by default. Passing onPress (without disabled) makes it a Pressable with accessibilityRole="button" and the given accessibilityLabel — a consumer building a real editable field (InputField\'s editable mode) relies on its own inner TextInput for accessibility instead.',
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'resting',
+        name: 'Resting',
+        node: (
+          <FieldContainer style={styles.fieldContainerDemo}>
+            <Text style={styles.fieldContainerText}>Field content</Text>
+          </FieldContainer>
+        ),
+      },
+      {
+        key: 'focused',
+        name: 'Focused',
+        props: { focused: true },
+        node: (
+          <FieldContainer focused style={styles.fieldContainerDemo}>
+            <Text style={styles.fieldContainerText}>Field content</Text>
+          </FieldContainer>
+        ),
+      },
+      {
+        key: 'disabled',
+        name: 'Disabled',
+        props: { disabled: true },
+        node: (
+          <FieldContainer disabled style={styles.fieldContainerDemo}>
+            <Text style={styles.fieldContainerText}>Field content</Text>
+          </FieldContainer>
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'pressed',
+        name: 'Pressed (caller-driven)',
+        props: { pressed: true },
+        node: (
+          <FieldContainer pressed style={styles.fieldContainerDemo}>
+            <Text style={styles.fieldContainerText}>Field content</Text>
+          </FieldContainer>
+        ),
+      },
+      {
+        key: 'pressable',
+        name: 'Pressable (with onPress)',
+        node: (
+          <FieldContainer onPress={() => {}} accessibilityLabel="Field content" style={styles.fieldContainerDemo}>
+            <Text style={styles.fieldContainerText}>Field content</Text>
+          </FieldContainer>
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,99 @@
+import React from 'react';
+import { View, Pressable, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS } from '../../tokens';
+import { useSurfaceTone } from '../Surface';
+import type { FieldContainerProps } from './FieldContainer.types';
+
+/**
+ * The shared "field" chrome: medium radius, a 1px subtle border that darkens to border.dark on
+ * focus, and a fill that contrasts with whatever it's actually placed on — reads the ambient
+ * `useSurfaceTone()` (see `Surface`) rather than assuming one fixed background. On the default
+ * white tone it's a translucent recessed fill (the same adaptive-overlay mechanism SegmentedToggle's
+ * track and Button's own `secondary` variant use); on a `muted` surface (wrapped in
+ * `<Surface tone="muted">`) it flips to opaque white instead, so it never goes invisible against
+ * whatever's behind it either way. It owns *only* the container look — consumers (InputField,
+ * TextArea, SearchField) supply their own layout (height, padding, content) via `style` and
+ * children, so a single-line row and a multiline area stay visually consistent.
+ */
+export function FieldContainer({
+  focused = false,
+  disabled = false,
+  onPress,
+  pressed = false,
+  accessibilityLabel,
+  accessibilityState,
+  style,
+  children,
+}: FieldContainerProps) {
+  const onWhite = useSurfaceTone() === 'white';
+  const toneStyle = onWhite ? stylesOnWhite : stylesOnMuted;
+
+  const stylesFor = (isPressed: boolean) => [
+    styles.base,
+    toneStyle.rest,
+    disabled && toneStyle.disabled,
+    !disabled && focused && toneStyle.focused,
+    !disabled && isPressed && toneStyle.pressed,
+    style,
+  ];
+
+  if (onPress && !disabled) {
+    // Pressable owns the pressed feedback; OR in the caller-driven `pressed` so both sources work.
+    return (
+      <Pressable
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel}
+        accessibilityState={accessibilityState}
+        style={({ pressed: p }) => stylesFor(p || pressed)}
+      >
+        {children}
+      </Pressable>
+    );
+  }
+
+  // Non-Pressable (e.g. editable, or a disabled picker) fields still honour the caller-driven
+  // pressed treatment. When the caller gave this container a name/state, keep it an accessible
+  // button element — a disabled picker must announce as "…, button, disabled", not vanish from
+  // the accessibility tree just because it lost its Pressable.
+  const stillAccessible = accessibilityLabel != null || accessibilityState != null;
+  return (
+    <View
+      style={stylesFor(pressed)}
+      accessible={stillAccessible || undefined}
+      accessibilityRole={stillAccessible ? 'button' : undefined}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={accessibilityState}
+    >
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  base: {
+    borderRadius: DS_RADIUS.medium,
+    borderWidth: 1,
+    borderColor: DS_SEMANTIC.border.subtle,
+  },
+});
+
+// On a white surface: translucent recessed fill, tuned pressed/disabled versions of that same
+// overlay (recessedPressed/recessedDisabled — not a second overlay stacked on top, see Button's own
+// `secondary` variant for why).
+const stylesOnWhite = StyleSheet.create({
+  rest: { backgroundColor: DS_SEMANTIC.surface.recessed },
+  focused: { borderColor: DS_SEMANTIC.border.dark },
+  pressed: { backgroundColor: DS_SEMANTIC.surface.recessedPressed },
+  disabled: { backgroundColor: DS_SEMANTIC.surface.recessedDisabled, borderColor: DS_SEMANTIC.border.subtle },
+});
+
+// On a muted surface: opaque white fill instead (recessed would barely read against an
+// already-grey background) — pressed/disabled are the plain surface tokens for "a white
+// surface, tapped" / "a white surface, muted-out", the same ones other white-fill surfaces use.
+const stylesOnMuted = StyleSheet.create({
+  rest: { backgroundColor: DS_SEMANTIC.surface.white },
+  focused: { borderColor: DS_SEMANTIC.border.dark },
+  pressed: { backgroundColor: DS_SEMANTIC.surface.onTap },
+  disabled: { backgroundColor: DS_SEMANTIC.surface.muted, borderColor: DS_SEMANTIC.border.subtle },
+});

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

@@ -0,0 +1,27 @@
+import type React from 'react';
+import type { AccessibilityState, StyleProp, ViewStyle } from 'react-native';
+
+export interface FieldContainerProps {
+  /** Focused → border darkens to border.dark. */
+  focused?: boolean;
+  /** Disabled → washed-out fill, non-interactive. The exact fill adapts to the ambient surface tone
+   *  (see FieldContainer.tsx's per-tone StyleSheets). */
+  disabled?: boolean;
+  /** When set (and not disabled), the container is a Pressable with tap feedback — the pressed fill
+   *  adapts to the ambient surface tone (see FieldContainer.tsx). */
+  onPress?: () => void;
+  /** Caller-driven pressed state — applies the same pressed treatment without an `onPress` Pressable
+   *  (e.g. an editable field that drives this from the TextInput's onPressIn/onPressOut). */
+  pressed?: boolean;
+  /** Only used when onPress is set. */
+  accessibilityLabel?: string;
+  /** Forwarded to the container (Pressable or plain View) — lets a picker-style consumer announce
+   *  `{ disabled, expanded }`. When set (or when `accessibilityLabel` is), even the non-Pressable
+   *  branch stays an accessible `button` element, so e.g. a disabled Dropdown still announces as
+   *  "…, button, disabled" instead of disappearing from the accessibility tree. */
+  accessibilityState?: AccessibilityState;
+  /** Layout the consumer adds on top of the shared chrome (height, padding, flex direction…). */
+  style?: StyleProp<ViewStyle>;
+  /** The field's own layout, height, padding, and content. */
+  children: React.ReactNode;
+}

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

@@ -0,0 +1,2 @@
+export { FieldContainer } from './FieldContainer';
+export type { FieldContainerProps } from './FieldContainer.types';

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

@@ -0,0 +1,18 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { InputClearButton } from './InputClearButton';
+
+export default defineCatalogPage({
+  component: 'InputClearButton',
+  group: 'Sub-Parts',
+  description: 'The clear (×) button InputField and SearchField both show once a field is active and holds a value — a filled circle-x icon sized to reach the 44pt touch target via hitSlop, not visual size.',
+  a11y: 'A Pressable with accessibilityRole="button" and the given (or default "Clear field") accessibilityLabel; hitSlop of 10 on every side pads its 24×24 visual size out to the 44pt minimum.',
+  variants: {
+    items: [{ key: 'default', name: 'Default', node: <InputClearButton onPress={() => {}} /> }],
+  },
+  states: {
+    items: [
+      { key: 'custom-label', name: 'Custom accessibility label', node: <InputClearButton onPress={() => {}} accessibilityLabel="Clear search" /> },
+    ],
+  },
+});

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

@@ -0,0 +1,63 @@
+import React, { useState } from 'react';
+import { Pressable, StyleSheet, Platform } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+
+/** Matches iOS search-field clear control (circle + ×). */
+const CLEAR_ICON_SIZE = 20;
+
+export interface InputClearButtonProps {
+  /** Tap handler — typically clears the paired field and refocuses it. */
+  onPress: () => void;
+  /** Accessible name — InputField/SearchField pass a field-specific label (e.g. "Clear To"). */
+  accessibilityLabel?: string;
+}
+
+// Web-only: this button only ever renders while its paired field is focused/active — but this
+// Pressable is a plain (non-focusable) element, so the browser's default mousedown behaviour blurs
+// the field the instant the press starts. That blur triggers InputField/SearchField's own
+// `focused` state to flip synchronously, which unmounts THIS Pressable before its own press event
+// ever gets to fire — the clear action is silently dropped (confirmed: neither onPress nor
+// onPressIn ran). Blocking the browser's default mousedown behaviour keeps the field focused
+// through the whole press, so this Pressable is still mounted by the time onPress fires. Native has
+// no such default-focus-shift-on-press behaviour, so this is web-only.
+const preventFocusSteal = Platform.OS === 'web' ? { onMouseDown: (e: { preventDefault: () => void }) => e.preventDefault() } : null;
+
+export function InputClearButton({
+  onPress,
+  accessibilityLabel = 'Clear field',
+}: InputClearButtonProps) {
+  const [focused, setFocused] = useState(false);
+  return (
+    <Pressable
+      onPress={onPress}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      {...preventFocusSteal}
+      // 24x24 visual + 10 on every side reaches the 44pt touch-target minimum.
+      hitSlop={10}
+      // Keyboard focus shows the same highlight as a press (same policy as ListItem/SegmentedToggle).
+      style={({ pressed }) => [styles.button, (pressed || focused) && styles.buttonPressed]}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+    >
+      {/* A solid filled icon reads much heavier than the old stroke ×  — muted keeps it a quiet
+          utility action rather than competing with the field's own value text. */}
+      <Icon name="circle-x" size={CLEAR_ICON_SIZE} color={DS_SEMANTIC.text.muted} />
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    width: 24,
+    height: 24,
+    borderRadius: DS_RADIUS.round,
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+  },
+  buttonPressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+});

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

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

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

@@ -0,0 +1,76 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { InputField } from './InputField';
+
+function InputFieldDemo() {
+  const [value, setValue] = useState('');
+  return (
+    <InputField
+      label="From"
+      value={value}
+      onChangeText={setValue}
+      editable
+      placeholder="Search a station"
+    />
+  );
+}
+
+export default defineCatalogPage({
+  component: 'InputField',
+  group: 'Inputs',
+  description: 'A floating-label field. Resting: a centred, body-sized label with no border. Active (focused, or picker with active set) or filled: the label floats to a small top caption, row 2 shows the value/input, and a border fades in while active.',
+  whenToUse: 'A named field with a fixed identity ("To", "Arrive by") across the interaction. For free-text search with no floating label, use SearchField; for one of a small known set of choices, use Dropdown.',
+  a11y: 'The editable mode is a live TextInput; the picker mode is a Pressable row. Either mode shows a clear button while active (focused, or active for a picker) with a value set. Provide a meaningful label.',
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'default',
+        name: 'Default',
+        props: { label: 'To' },
+        node: <InputField label="To" placeholder="Search a station" onPress={() => {}} />,
+      },
+      {
+        key: 'icon-label',
+        name: 'Icon label',
+        props: { label: 'icon' },
+        node: <InputField label="icon" labelIcon="flag" value="Custom stop" onPress={() => {}} />,
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      { key: 'editable', name: 'Editable', props: { label: 'From' }, node: <InputFieldDemo /> },
+      {
+        key: 'picker',
+        name: 'Picker (filled)',
+        node: <InputField label="To" value="Grand Central" placeholder="Search a station" onPress={() => {}} />,
+      },
+      {
+        key: 'active',
+        name: 'Active (external picker open)',
+        node: <InputField label="To" value="Grand Central" placeholder="Search a station" active onPress={() => {}} />,
+      },
+      {
+        key: 'optional',
+        name: 'Optional label',
+        props: { label: 'Name' },
+        node: <InputField label="Name" placeholder="Nickname" optional onPress={() => {}} />,
+      },
+      {
+        key: 'value-icon',
+        name: 'Value with icon',
+        props: { label: 'Walk time' },
+        node: <InputField label="Walk time" value="8 min" valueIcon="footprints" />,
+      },
+      {
+        key: 'value-accent',
+        name: 'Accent value',
+        props: { label: 'Arrive by' },
+        node: <InputField label="Arrive by" value="9:12 AM" valueAccent />,
+      },
+      { key: 'disabled', name: 'Disabled', node: <InputField label="Arrive by" value="9:12 AM" disabled /> },
+    ],
+  },
+});