[Shadows] Add initial readme file with simple usage guide.

PiperOrigin-RevId: 368423494

Author: yarneo

components/Shadow/README.md

@@ -0,0 +1,76 @@
+# Shadow
+
+Provides lightweight classes that hold shadow properties that each correspond to an elevation.
+
+This library provides two immutable types that are created via builder APIs:
+MDCShadowsCollection and MDCShadow. This library works with standard CALayer shadow APIs in order
+to optimize for performance. UIView’s layer shadow properties are set directly, including:
+shadowOffset, shadowRadius, shadowOpacity, shadowColor, and shadowPath. We ensure that
+shadowPath is consistently set alongside the other properties in order for shadows to benefit
+from the performance gains that shadowPath provides.
+
+This library is part of an effort to simplify shadows in MDC, with the intent of deleting the
+MDCShadowLayer component entirely.
+
+## Usage
+
+We want to provide a simple API to integrate this shadow solution. Therefore, we leaned on providing only one type of configuration method that should be re-called in the view’s lifecycle. Namely, the method should be the C function MDCConfigureShadowForView.
+
+MDCConfigureShadowForView should be called in the start of the view’s lifecycle, i.e. during initialization, so that the shadowRadius, shadowOffset, shadowColor, and shadowOpacity are set on the layer.
+
+MDCConfigureShadowForView should also be called when the elevation is changed for the view i.e. it is set by the client, or there is a state change that also changes the elevation. This is to ensure that the right shadow values for that elevation are set on the layer.
+Lastly, MDCConfigureShadowForView should be called in layoutSubviews, to ensure that the shadowPath is set using the most upto date bounds and cornerRadius of the view.
+
+### Importing
+
+Before using Shadow, you'll need to import it:
+
+#### Swift
+```swift
+import MaterialComponents
+
+var shadowsCollection: MDCShadowsCollection
+let shadow = MDCShadowBuilder.builder(withOpacity:0.1, radius: 0.2, offset: CGSize(0.3, 0.4)).build()
+let shadowsBuilder = MDCShadowsCollectionBuilder.builder(withShadow:shadow forElevation:0)
+let shadowValuesForElevation = [1: MDCShadowBuilder.builder(withOpacity:0.3,
+                                                            radius: 0.4,
+                                                            offset: CGSize(0.5, 0.6)).build()]
+shadowsBuilder.addShadows(forElevation:shadowValuesForElevation)
+shadowsCollection = shadowsBuilder.build()
+
+...
+
+func updateShadow() {
+  MDCConfigureShadowForView(self,
+                            self.shadowsCollection.shadow(forElevation:self.mdc_currentElevation),
+                            self.shadowColor)
+}
+```
+
+#### Objective-C
+```objc
+#import "MaterialShadow.h"
+
+MDCShadowsCollection *shadowsCollection;
+MDCShadow *shadow =
+    [[MDCShadowBuilder builderWithOpacity:0.1
+                                   radius:0.2
+                                   offset:CGSizeMake(0.3, 0.4)] build];
+MDCShadowsCollectionBuilder *shadowsBuilder =
+    [MDCShadowsCollectionBuilder builderWithShadow:shadow forElevation:0];
+NSDictionary<NSNumber *, MDCShadow *> *shadowValuesForElevation = @{
+  @1 : [[MDCShadowBuilder builderWithOpacity:0.3
+                                      radius:0.4
+                                      offset:CGSizeMake(0.5, 0.6)] build],
+};
+[shadowsBuilder addShadowsForElevations:shadowValuesForElevation];
+shadowsCollection = [shadowsBuilder build];
+
+...
+
+- (void)updateShadow {
+  MDCConfigureShadowForView(self,
+                            [self.shadowsCollection shadowForElevation:self.mdc_currentElevation],
+                            self.shadowColor);
+}
+```