@krapwoo/ds-viewer 0.6.11 → 0.8.0

package/starter-kit/pages/Motion.catalog.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, Text, StyleSheet, Easing } from 'react-native';
-import { defineCatalogPage, DividedStack, VariantGroup, TokenRow, MotionSpecimen } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, TokenRow, TokenRowGroup, MotionSpecimen } from '@krapwoo/ds-viewer';
 import {
   DS_MOTION_DURATION,
   DS_MOTION_DURATION_STEPS,
@@ -26,98 +26,127 @@ const styles = StyleSheet.create({
   previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
   previewValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
   durationBar: { height: 12, borderRadius: DS_RADIUS.small, backgroundColor: DS_SEMANTIC.emphasis.info },
-  // Spring config — a wrapping grid of key/value fields, since DS_MOTION_SPRING has 6 fields, too
-  // many to lay out as a single previewRow.
-  springGrid: { flexDirection: 'row', flexWrap: 'wrap', gap: DS_SPACING[600] },
-  springField: { width: 168, gap: DS_SPACING[100] },
   easingValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted, fontFamily: 'Menlo' },
+
+  // A spring is a config object, not a step on a scale: six named fields that only mean anything
+  // together. Laid out with the fields down the side and each spring token as its own column, so a
+  // second spring adds a column instead of repeating all six names, and `damping` reads across
+  // tokens on one line. The field vocabulary is fixed; the number of tokens is what grows.
+  springRow: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: DS_SPACING[600],
+    paddingVertical: DS_SPACING[400],
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderColor: DS_SEMANTIC.border.light,
+  },
+  springRowLast: { borderBottomWidth: 0 },
+  // Wide enough that `restDisplacementThreshold` sits on one line instead of breaking mid-word,
+  // which is what the previous fixed 168px field did to it.
+  springField: { width: 210, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
+  springCell: { flex: 1, minWidth: 130 },
+  springValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.regular },
+  springNote: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
 });
 
-function MotionGallery() {
-  const maxDuration = Math.max(...Object.values(DS_MOTION_DURATION));
-  const maxLoopDuration = Math.max(...Object.values(DS_MOTION_LOOP_DURATION));
+/** Every spring token on the page. One today — the shape is what lets a second arrive without
+ *  redesigning the section. */
+const SPRINGS: Record<string, typeof DS_MOTION_SPRING> = { snappy: DS_MOTION_SPRING };
+const SPRING_NOTES: Record<string, string> = { snappy: DS_MOTION_SPRING_USE };
+const SPRING_FIELDS = Object.keys(DS_MOTION_SPRING) as (keyof typeof DS_MOTION_SPRING)[];
+
+function SpringTable() {
+  const names = Object.keys(SPRINGS);
+  const cells = (render: (name: string) => React.ReactNode) =>
+    names.map((name) => (
+      <View key={name} style={styles.springCell}>
+        {render(name)}
+      </View>
+    ));
   return (
-    <DividedStack>
-      <VariantGroup name="Duration" desc="one-shot transitions — reach for base (240ms) first" align="left">
-        <View style={styles.tokenStack}>
-          {DS_MOTION_DURATION_STEPS.map((step, i) => (
-            <TokenRow key={step} use={DS_MOTION_DURATION_USE[step]} last={i === DS_MOTION_DURATION_STEPS.length - 1}>
-              <View style={styles.rowContent}>
-                <View style={styles.previewRow}>
-                  <Text style={styles.previewLabel}>{step}</Text>
-                  <View style={[styles.durationBar, { width: (DS_MOTION_DURATION[step] / maxDuration) * 120 }]} />
-                  <Text style={styles.previewValue}>{DS_MOTION_DURATION[step]}ms</Text>
-                </View>
-                <MotionSpecimen
-                  kind="timing"
-                  duration={DS_MOTION_DURATION[step]}
-                  easing={Easing.bezier(...DS_MOTION_EASING.standard)}
-                  label={`${DS_MOTION_DURATION[step]}ms · standard easing`}
-                />
-              </View>
-            </TokenRow>
-          ))}
+    <View>
+      {/* A single spring needs no column header — the section title is already its name. */}
+      {names.length > 1 ? (
+        <View style={styles.springRow}>
+          <Text style={styles.springField}>field</Text>
+          {cells((name) => <Text style={styles.previewLabel}>{name}</Text>)}
         </View>
-      </VariantGroup>
-      <VariantGroup name="Loop duration" desc="continuous, indeterminate loops — a spinner or a shimmer pulse, not a one-shot transition" align="left">
-        <View style={styles.tokenStack}>
-          {DS_MOTION_LOOP_DURATION_STEPS.map((step, i) => (
-            <TokenRow key={step} use={DS_MOTION_LOOP_DURATION_USE[step]} last={i === DS_MOTION_LOOP_DURATION_STEPS.length - 1}>
-              <View style={styles.rowContent}>
-                <View style={styles.previewRow}>
-                  <Text style={styles.previewLabel}>{step}</Text>
-                  <View style={[styles.durationBar, { width: (DS_MOTION_LOOP_DURATION[step] / maxLoopDuration) * 120 }]} />
-                  <Text style={styles.previewValue}>{DS_MOTION_LOOP_DURATION[step]}ms</Text>
-                </View>
-                <MotionSpecimen
-                  kind="timing"
-                  duration={DS_MOTION_LOOP_DURATION[step]}
-                  easing={Easing.bezier(...DS_MOTION_EASING.standard)}
-                  label={`${DS_MOTION_LOOP_DURATION[step]}ms · one cycle`}
-                />
-              </View>
-            </TokenRow>
-          ))}
+      ) : null}
+      {SPRING_FIELDS.map((field) => (
+        <View key={String(field)} style={styles.springRow}>
+          <Text style={styles.springField}>{String(field)}</Text>
+          {cells((name) => <Text style={styles.springValue}>{String(SPRINGS[name][field])}</Text>)}
         </View>
-      </VariantGroup>
-      <VariantGroup name="Easing" desc="cubic-bezier curves — convert with Easing.bezier(...DS_MOTION_EASING.x)" align="left">
-        <View style={styles.tokenStack}>
-          {DS_MOTION_EASING_STEPS.map((step, i) => (
-            <TokenRow key={step} use={DS_MOTION_EASING_USE[step]} last={i === DS_MOTION_EASING_STEPS.length - 1}>
-              <View style={styles.rowContent}>
-                <View style={styles.previewRow}>
-                  <Text style={styles.previewLabel}>{step}</Text>
-                  <Text style={styles.easingValue}>cubic-bezier({DS_MOTION_EASING[step].join(', ')})</Text>
-                </View>
-                <MotionSpecimen
-                  kind="timing"
-                  duration={DS_MOTION_DURATION.base}
-                  easing={Easing.bezier(...DS_MOTION_EASING[step])}
-                  label={`${DS_MOTION_DURATION.base}ms · ${step}`}
-                />
+      ))}
+      <View style={styles.springRow}>
+        <Text style={styles.springField}>preview</Text>
+        {cells((name) => (
+          <MotionSpecimen kind="spring" spring={SPRINGS[name]} label="Animated.spring(value, DS_MOTION_SPRING)" />
+        ))}
+      </View>
+      <View style={[styles.springRow, styles.springRowLast]}>
+        <Text style={styles.springField}>when to use</Text>
+        {cells((name) => <Text style={styles.springNote}>{SPRING_NOTES[name]}</Text>)}
+      </View>
+    </View>
+  );
+}
+
+/** A millisecond scale: a bar for the relative length, then the real animation at that duration. */
+function DurationRows({ steps, values, notes, label }: {
+  steps: readonly string[];
+  values: Record<string, number>;
+  notes: Record<string, string>;
+  label: (ms: number) => string;
+}) {
+  const max = Math.max(...steps.map((step) => values[step]));
+  return (
+    <TokenRowGroup>
+      <View style={styles.tokenStack}>
+        {steps.map((step, i) => (
+          <TokenRow key={step} use={notes[step]} last={i === steps.length - 1} notePlacement="right">
+            <View style={styles.rowContent}>
+              <View style={styles.previewRow}>
+                <Text style={styles.previewLabel}>{step}</Text>
+                <View style={[styles.durationBar, { width: (values[step] / max) * 120 }]} />
+                <Text style={styles.previewValue}>{values[step]}ms</Text>
               </View>
-            </TokenRow>
-          ))}
-        </View>
-      </VariantGroup>
-      <VariantGroup name="Spring" desc="for Animated.spring(value, DS_MOTION_SPRING) — snap-point transitions, not fixed-duration timing">
-        <View style={styles.tokenStack}>
-          <TokenRow use={DS_MOTION_SPRING_USE} last>
+              <MotionSpecimen
+                kind="timing"
+                duration={values[step]}
+                easing={Easing.bezier(...DS_MOTION_EASING.standard)}
+                label={label(values[step])}
+              />
+            </View>
+          </TokenRow>
+        ))}
+      </View>
+    </TokenRowGroup>
+  );
+}
+
+function EasingRows() {
+  return (
+    <TokenRowGroup>
+      <View style={styles.tokenStack}>
+        {DS_MOTION_EASING_STEPS.map((step, i) => (
+          <TokenRow key={step} use={DS_MOTION_EASING_USE[step]} last={i === DS_MOTION_EASING_STEPS.length - 1} notePlacement="right">
             <View style={styles.rowContent}>
-              <View style={styles.springGrid}>
-                {(Object.entries(DS_MOTION_SPRING) as [string, number | boolean][]).map(([key, value]) => (
-                  <View key={key} style={styles.springField}>
-                    <Text style={styles.previewLabel}>{key}</Text>
-                    <Text style={styles.previewValue}>{String(value)}</Text>
-                  </View>
-                ))}
+              <View style={styles.previewRow}>
+                <Text style={styles.previewLabel}>{step}</Text>
+                <Text style={styles.easingValue}>cubic-bezier({DS_MOTION_EASING[step].join(', ')})</Text>
               </View>
-              <MotionSpecimen kind="spring" spring={DS_MOTION_SPRING} label="Animated.spring(value, DS_MOTION_SPRING)" />
+              <MotionSpecimen
+                kind="timing"
+                duration={DS_MOTION_DURATION.base}
+                easing={Easing.bezier(...DS_MOTION_EASING[step])}
+                label={`${DS_MOTION_DURATION.base}ms · ${step}`}
+              />
             </View>
           </TokenRow>
-        </View>
-      </VariantGroup>
-    </DividedStack>
+        ))}
+      </View>
+    </TokenRowGroup>
   );
 }
 
@@ -125,5 +154,44 @@ export default defineCatalogPage({
   group: 'Tokens',
   description: 'Duration (one-shot transitions), loop duration (continuous, indeterminate loops like Loading/Shimmer), easing, and spring tokens for transitions/animations. Easings are cubic-bezier tuples, not Easing objects, so the token file stays free of any react-native import. The spring config is grounded in the metro-native app this template was extracted from, where the same values drive its BottomSheet\'s snap-point transitions.',
   tokenGallery: true,
-  render: () => <MotionGallery />,
+  // A card per kind of token. Durations are a scale in milliseconds, easings are bezier curves and
+  // a spring is a config object: four different things that read as one long box when they share a
+  // single card. One column, because every section's rows want the full width.
+  tokenColumns: 1,
+  tokenSections: [
+    {
+      title: 'Duration',
+      desc: 'one-shot transitions — reach for base (240ms) first',
+      render: () => (
+        <DurationRows
+          steps={DS_MOTION_DURATION_STEPS}
+          values={DS_MOTION_DURATION}
+          notes={DS_MOTION_DURATION_USE}
+          label={(ms) => `${ms}ms · standard easing`}
+        />
+      ),
+    },
+    {
+      title: 'Loop duration',
+      desc: 'continuous, indeterminate loops — a spinner or a shimmer pulse, not a one-shot transition',
+      render: () => (
+        <DurationRows
+          steps={DS_MOTION_LOOP_DURATION_STEPS}
+          values={DS_MOTION_LOOP_DURATION}
+          notes={DS_MOTION_LOOP_DURATION_USE}
+          label={(ms) => `${ms}ms · one cycle`}
+        />
+      ),
+    },
+    {
+      title: 'Easing',
+      desc: 'cubic-bezier curves — convert with Easing.bezier(...DS_MOTION_EASING.x)',
+      render: () => <EasingRows />,
+    },
+    {
+      title: 'Spring',
+      desc: 'for Animated.spring(value, DS_MOTION_SPRING) — snap-point transitions, not fixed-duration timing',
+      render: () => <SpringTable />,
+    },
+  ],
 });

package/starter-kit/pages/Radius.catalog.tsx

@@ -1,29 +1,33 @@
 import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, TokenRow } from '@krapwoo/ds-viewer';
-import { DS_RADIUS, DS_RADIUS_STEPS, DS_RADIUS_USE, DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../tokens';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, TokenGrid, TokenTile } from '@krapwoo/ds-viewer';
+import { DS_RADIUS, DS_RADIUS_STEPS, DS_RADIUS_USE, DS_SEMANTIC } from '../tokens';
 
 const styles = StyleSheet.create({
-  tokenStack: { gap: DS_SPACING[800] },
-  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
-  previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
-  previewValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
-  radiusBox: { width: 40, height: 40, backgroundColor: DS_SEMANTIC.emphasis.info, borderWidth: StyleSheet.hairlineWidth, borderColor: DS_SEMANTIC.border.light },
+  // Square, so the corner is read as a corner rather than as the end of a bar. Large enough that
+  // 4px and 8px are still telling apart at a glance.
+  radiusBox: {
+    width: 64,
+    height: 64,
+    backgroundColor: DS_SEMANTIC.emphasis.info,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: DS_SEMANTIC.border.light,
+  },
 });
 
 function RadiusGallery() {
   return (
-    <View style={styles.tokenStack}>
-      {DS_RADIUS_STEPS.map((step, i) => (
-        <TokenRow key={step} use={DS_RADIUS_USE[step]} last={i === DS_RADIUS_STEPS.length - 1}>
-          <View style={styles.previewRow}>
-            <Text style={styles.previewLabel}>{step}</Text>
-            <View style={[styles.radiusBox, { borderRadius: DS_RADIUS[step] }]} />
-            <Text style={styles.previewValue}>{DS_RADIUS[step]}px</Text>
-          </View>
-        </TokenRow>
+    // Tiles, not rows: a radius preview is small and self-contained, so the steps belong side by
+    // side where `xs` can be compared against `large` directly — which is the only way to read a
+    // scale. A row each would put them 100px apart vertically and leave the right half of every
+    // row empty.
+    <TokenGrid minTileWidth={150}>
+      {DS_RADIUS_STEPS.map((step) => (
+        <TokenTile key={step} name={step} value={`${DS_RADIUS[step]}px`} note={DS_RADIUS_USE[step]}>
+          <View style={[styles.radiusBox, { borderRadius: DS_RADIUS[step] }]} />
+        </TokenTile>
       ))}
-    </View>
+    </TokenGrid>
   );
 }
 

package/starter-kit/pages/Shadow.catalog.tsx

@@ -1,28 +1,40 @@
 import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, TokenRow } from '@krapwoo/ds-viewer';
-import { DS_RADIUS, DS_SEMANTIC, DS_SHADOW, DS_SHADOW_USE, DS_SPACING, DS_TYPOGRAPHY, type ShadowToken } from '../tokens';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, TokenGrid, TokenTile } from '@krapwoo/ds-viewer';
+import { DS_RADIUS, DS_SEMANTIC, DS_SHADOW, DS_SHADOW_USE, DS_SPACING, type ShadowToken } from '../tokens';
 
 const styles = StyleSheet.create({
-  tokenStack: { gap: DS_SPACING[800] },
-  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
-  previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
-  shadowBox: { width: 56, height: 40, borderRadius: DS_RADIUS.medium, backgroundColor: DS_SEMANTIC.surface.white },
+  // A shadow is cast *onto* something. On the catalog's own white card the elevated surface is
+  // white on white and the token reads as an empty space, so each tile gives it a tinted backdrop
+  // to fall on — the same reason a product screen sits a card on a page colour, not on paper.
+  stage: {
+    backgroundColor: DS_SEMANTIC.surface.main,
+    borderRadius: DS_RADIUS.small,
+    paddingVertical: DS_SPACING[800],
+    alignItems: 'center',
+  },
+  surface: {
+    width: 76,
+    height: 48,
+    borderRadius: DS_RADIUS.medium,
+    backgroundColor: DS_SEMANTIC.surface.white,
+  },
 });
 
 function ShadowGallery() {
   const steps = Object.keys(DS_SHADOW) as ShadowToken[];
   return (
-    <View style={styles.tokenStack}>
-      {steps.map((step, i) => (
-        <TokenRow key={step} use={DS_SHADOW_USE[step]} last={i === steps.length - 1}>
-          <View style={styles.previewRow}>
-            <Text style={styles.previewLabel}>{step}</Text>
-            <View style={[styles.shadowBox, DS_SHADOW[step]]} />
+    // Tiles: an elevation preview is small and self-contained, and seeing `resting` beside
+    // `bottomSheet` is the only way to judge how much stronger one lift is than another.
+    <TokenGrid minTileWidth={170}>
+      {steps.map((step) => (
+        <TokenTile key={step} name={step} note={DS_SHADOW_USE[step]}>
+          <View style={styles.stage}>
+            <View style={[styles.surface, DS_SHADOW[step]]} />
           </View>
-        </TokenRow>
+        </TokenTile>
       ))}
-    </View>
+    </TokenGrid>
   );
 }