@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

@@ -0,0 +1,69 @@
+import React, { useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Dropdown } from './Dropdown';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  // Dropdown demo — fills PhoneFrame edge-to-edge (`flex:1` + `alignSelf:'stretch'` override
+  // PhoneFrame's own `alignItems/justifyContent:'center'`, which centers-and-shrinks BottomSheetDemo's
+  // trigger button just fine but would otherwise leave this wrapper short and centered too). Dropdown's
+  // own BottomSheet is a sibling of its trigger in the same tree position, so its absolute overlay
+  // fills *this* box — it needs to be the full frame, not a small box hugging just the trigger.
+  dropdownFrameContent: { flex: 1, alignSelf: 'stretch', padding: DS_SPACING[800] },
+});
+
+const SAMPLE_DROPDOWN_OPTIONS = [
+  { value: 'uptown', label: 'Uptown & The Bronx' },
+  { value: 'downtown', label: 'Downtown & Brooklyn' },
+  { value: 'crosstown', label: 'Crosstown' },
+];
+
+function DropdownDemo() {
+  const [value, setValue] = useState('uptown');
+  return (
+    <PhoneFrame>
+      <View style={styles.dropdownFrameContent}>
+        <Dropdown
+          label="Direction"
+          value={value}
+          onChange={setValue}
+          placeholder="Choose a direction"
+          options={SAMPLE_DROPDOWN_OPTIONS}
+        />
+      </View>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'Dropdown',
+  group: 'Inputs',
+  description: 'A labelled field that opens a BottomSheet picker on tap — the "bottom sheet picker" interaction: tap the trigger, pick an option from the sheet, it closes.',
+  whenToUse: 'The answer is one of a small, known set of choices — never free text. For free-text filtering, use SearchField; for a named field with a fixed identity, use InputField.',
+  a11y: 'The trigger is a Pressable (via FieldContainer) with accessibilityRole="button". Options render as accessibilityRole="radio" inside a "radiogroup", with accessibilityState.checked reflecting the current selection.',
+  variants: {
+    itemsFill: true,
+    items: [{ key: 'default', name: 'Default (tap to open)', node: <DropdownDemo /> }],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'placeholder',
+        name: 'Placeholder',
+        node: <Dropdown label="Direction" placeholder="Choose a direction" options={SAMPLE_DROPDOWN_OPTIONS} onChange={() => {}} />,
+      },
+      {
+        key: 'no-label',
+        name: 'No label',
+        node: <Dropdown value="uptown" options={SAMPLE_DROPDOWN_OPTIONS} onChange={() => {}} />,
+      },
+      {
+        key: 'disabled',
+        name: 'Disabled',
+        node: <Dropdown label="Direction" value="uptown" options={SAMPLE_DROPDOWN_OPTIONS} onChange={() => {}} disabled />,
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,162 @@
+import React, { useEffect, useState } from 'react';
+import { View, Text, Pressable, Modal, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { FieldContainer } from '../FieldContainer';
+import { BottomSheet, useInsideBottomSheetWarning } from '../BottomSheet';
+import { TopNav } from '../TopNav';
+import { Button } from '../Button';
+import { Icon } from '../../icons/Icon.native';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_ICON_SIZE, DS_MOTION_DURATION, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+
+export interface DropdownOption {
+  value: string;
+  label: string;
+}
+
+export interface DropdownProps {
+  /** Field label shown above the value. Generic text (unlike InputField's fixed label set) since a
+   *  dropdown's label is app-specific. */
+  label?: string;
+  /** Selected option's value. */
+  value?: string;
+  /** Shown when no option is selected. */
+  placeholder?: string;
+  /** The selectable options. */
+  options: DropdownOption[];
+  /** Called with the newly selected option's value. */
+  onChange: (value: string) => void;
+  /** Non-interactive, dimmed; the picker won't open. */
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A labelled field (on the shared {@link FieldContainer} chrome) that opens a {@link BottomSheet}
+ * picker on tap — the "bottom sheet picker" interaction: tap the trigger, pick an option from the
+ * sheet, it closes. Value/selection are controlled by the caller; the sheet's own open/closed state
+ * is internal.
+ */
+export function Dropdown({ label, value, placeholder, options, onChange, disabled = false, style }: DropdownProps) {
+  useInsideBottomSheetWarning('Dropdown');
+  const [open, setOpen] = useState(false);
+  // The picker is portaled through a Modal (see the render below) specifically so it covers the
+  // whole screen even when Dropdown itself sits deep inside an arbitrary layout (a form row, a
+  // card, …) — BottomSheet's own absolutely-positioned overlay only fills whichever immediate
+  // parent View hosts it, which is wrong the moment that parent isn't already the full screen.
+  // `sheetMounted` keeps the Modal (and thus BottomSheet) around for BottomSheet's own exit
+  // animation instead of yanking it out of the DOM the instant `open` goes false.
+  const [sheetMounted, setSheetMounted] = useState(false);
+  useEffect(() => {
+    if (open) {
+      setSheetMounted(true);
+      return undefined;
+    }
+    const timer = setTimeout(() => setSheetMounted(false), DS_MOTION_DURATION.fast);
+    return () => clearTimeout(timer);
+  }, [open]);
+  const selected = options.find((o) => o.value === value);
+  const hasValue = !!selected;
+
+  const handleSelect = (optionValue: string) => {
+    onChange(optionValue);
+    setOpen(false);
+  };
+
+  const triggerAccessibilityLabel = [label, hasValue ? selected.label : placeholder].filter(Boolean).join(', ');
+
+  return (
+    <>
+      <FieldContainer
+        disabled={disabled}
+        onPress={disabled ? undefined : () => setOpen(true)}
+        // Label + state stay on even when disabled — FieldContainer keeps its View branch accessible,
+        // so a disabled dropdown still announces as "…, button, disabled" instead of vanishing.
+        accessibilityLabel={triggerAccessibilityLabel}
+        accessibilityState={{ disabled, expanded: open }}
+        style={[styles.trigger, style]}
+      >
+        <View style={styles.inner}>
+          <View style={styles.textColumn}>
+            {!!label && <Text style={[styles.label, disabled && styles.disabledText]}>{label}</Text>}
+            {/* Hint (empty) and disabled are DIFFERENT states with different colors — hint keeps the
+                text.muted placeholder tone; disabled goes a step lighter (text.disabled) so a
+                disabled dropdown holding a real value never reads as merely empty. */}
+            <Text
+              style={[styles.value, !hasValue && !disabled && styles.hint, disabled && styles.disabledText]}
+              numberOfLines={1}
+            >
+              {hasValue ? selected.label : placeholder}
+            </Text>
+          </View>
+          {/* Centred against the whole field (label + value stacked), not just the value line — this
+              row spans the full trigger height via `inner`'s own alignItems:'center'. */}
+          <Icon name="chevron-down" size={DS_ICON_SIZE.sm} color={disabled ? DS_SEMANTIC.text.disabled : DS_SEMANTIC.text.regular} />
+        </View>
+      </FieldContainer>
+      {sheetMounted && (
+        <Modal transparent animationType="none" onRequestClose={() => setOpen(false)}>
+          <BottomSheet
+            visible={open}
+            onDismiss={() => setOpen(false)}
+            header={
+              <TopNav
+                title={label ?? 'Select an option'}
+                trailing={
+                  <Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={() => setOpen(false)} />
+                }
+              />
+            }
+          >
+            <View style={styles.options} accessibilityRole="radiogroup">
+              {options.map((option) => {
+                const isSelected = option.value === value;
+                return (
+                  <Pressable
+                    key={option.value}
+                    onPress={() => handleSelect(option.value)}
+                    accessibilityRole="radio"
+                    accessibilityState={{ checked: isSelected }}
+                    style={({ pressed }) => [styles.option, pressed && styles.optionPressed]}
+                  >
+                    <Text style={[styles.optionLabel, isSelected && styles.optionLabelSelected]}>{option.label}</Text>
+                    {isSelected && <Icon name="check" size={DS_ICON_SIZE.sm} color={DS_SEMANTIC.emphasis.info} />}
+                  </Pressable>
+                );
+              })}
+            </View>
+          </BottomSheet>
+        </Modal>
+      )}
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  trigger: {
+    width: '100%',
+    paddingHorizontal: DS_SPACING[800],
+    paddingVertical: DS_SPACING[400],
+    // A labelled trigger is ~56pt already; this floor covers the label-less case, which would
+    // otherwise land under the 44pt minimum touch target.
+    minHeight: DS_A11Y_MIN_TOUCH_TARGET,
+    justifyContent: 'center',
+  },
+  inner: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[400] },
+  textColumn: { flex: 1, gap: DS_SPACING[100] },
+  label: { ...DS_TYPOGRAPHY.labelXs, color: DS_SEMANTIC.text.muted },
+  value: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
+  // Placeholder tone for the empty state.
+  hint: { color: DS_SEMANTIC.text.muted },
+  // Disabled text — one step lighter than `hint` (see DS_SEMANTIC.text.disabled's doc comment).
+  disabledText: { color: DS_SEMANTIC.text.disabled },
+  // No padding here — BottomSheet's own content area now supplies the standard 16px on all sides.
+  options: {},
+  option: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingVertical: DS_SPACING[600],
+  },
+  optionPressed: { backgroundColor: DS_SEMANTIC.interaction.pressed },
+  optionLabel: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
+  optionLabelSelected: { color: DS_SEMANTIC.emphasis.info },
+});

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

@@ -0,0 +1,2 @@
+export { Dropdown } from './Dropdown';
+export type { DropdownProps, DropdownOption } from './Dropdown';

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" /> },
+    ],
+  },
+});