@ambientcss/components 2.0.1 → 3.0.0

package/README.md

@@ -25,3 +25,38 @@ export function Example() {
   );
 }
 ```
+
+## Two layers
+
+Every control is a **mechanism** — kinematics, value, state and ARIA — plus a
+**skin**. The named components are presets that pair one with a set of parts;
+underneath, the mechanism has no appearance of its own and will wear whatever
+you give it.
+
+```tsx
+import { AmbientRotary, KnobBody, ScaleRing } from "@ambientcss/components";
+
+<AmbientRotary
+  value={gain} onChange={setGain}
+  travel={{ start: -135, sweep: 270 }}
+  input="drag"
+  className="amb-knob"
+  parts={{
+    panel: <ScaleRing count={13} />,
+    base: <KnobBody flush />,
+    actuator: <MyPointer />,
+  }}
+/>
+```
+
+Parts drop into four frames — `panel`, `base`, `actuator`, `fixture` — painted
+in that order, of which only `actuator` moves. The control publishes its state
+on its own root as `--ambx-percent`, `--ambx-angle`, `--ambx-size` and friends,
+so a part can be pure CSS with no React state at all; `useControlState()` is the
+same data typed, for parts that need JS.
+
+Mechanisms: `AmbientRotary`, `AmbientTravel`, `AmbientPress`, `AmbientLatch`,
+`AmbientBank`. Or take the hooks — `useRotary`, `useTravel`, `usePress`,
+`useLatch`, `useBank` — and render the markup yourself.
+
+Full guide: [Composing controls](https://kikkupico.github.io/ambientcss/ambient-components/composing).