@gradeui/ui 1.3.0 → 2.0.0

package/components/ui/background-fill.md

@@ -4,7 +4,7 @@ import: "@gradeui/ui"
 props:
   - type: "none" | "solid" | "gradient" | "image" | "video" | "shader" — which paint to render (required)
   - color?: string — solid fill; a token name (`primary`, `card`, `muted`, `accent`, `secondary`, `destructive`, `background`, `transparent`) or any CSS colour
-  - gradient?: { from?; via?; to?; angle? } — gradient stops (token names or CSS colours) + angle in degrees (default 135)
+  - gradient?: { from?; via?; to?; angle?; shape?; at?; size? } — stops are token names or CSS colours. shape: "linear" (default, uses `angle`, default 135°) | "radial" (uses `at` — CSS position like "top" / "30% 20%", default "center" — and optional `size` like "45rem 50rem", default farthest-corner)
   - src?: string — image or video URL
   - fit?: "cover" | "contain" | "fill" | "none" — object-fit for image/video (default "cover")
   - position?: string — CSS object/background position (default "center")
@@ -54,11 +54,24 @@ notes: |
   ### Type cheat-sheet
 
     - solid    — `color` (token or CSS colour). Cheapest.
-    - gradient — `gradient={{ from, via?, to, angle }}`. Tokens get wrapped in oklch() automatically.
+    - gradient — `gradient={{ from, via?, to, angle }}` for linear;
+                 `gradient={{ shape: "radial", at: "top", from, to }}` for a radial
+                 glow/wash. Tokens get wrapped in oklch() automatically.
     - image    — `src` + `fit` / `position`; set `repeat` (+ `tileSize`) for a tiled texture.
     - video    — `src` (autoplays muted + looped + inline).
     - shader   — `preset` OR `fragmentShader`, + `palette` / `postPreset`. Delegates to ThreeScene.
 
+  Anti-patterns to avoid:
+
+  - DO NOT build gradients with arbitrary-value Tailwind classes —
+    `bg-[radial-gradient(45rem_50rem_at_top,theme(colors.indigo.50),white)]`
+    renders NOTHING in the Studio preview (no runtime Tailwind compiler) and
+    `theme(colors.*)` colours ignore the active Grade theme. Use
+    `type="gradient"` with token stops instead — themeable, and it always renders.
+  - DO NOT hand-roll `style={{ backgroundImage: "linear-gradient(…)" }}` on the
+    frame itself when a BackgroundFill child does the same job — the fill layer
+    keeps the paint selectable/editable as a Fill in Studio's inspector.
+
   `opacity` + `blendMode` apply to every type — the same two controls as
   the inspector's Blending section, so a loud shader/image can be dialled
   back to a subtle wash behind text.
@@ -92,6 +105,19 @@ notes: |
 </Card>
 ```
 
+```jsx
+// Radial glow from the top of a hero — the token-true version of the
+// classic `radial-gradient(45rem 50rem at top, indigo-50, white)` wash.
+<section className="relative overflow-hidden">
+  <BackgroundFill
+    type="gradient"
+    gradient={{ shape: "radial", at: "top", size: "45rem 50rem", from: "primary", to: "background" }}
+    opacity={0.2}
+  />
+  <div className="relative z-10 py-24 text-center">…hero content…</div>
+</section>
+```
+
 ```jsx
 // Image background, cover-fit, with a blend mode.
 <div className="relative h-64 overflow-hidden rounded-lg">

package/components/ui/logo.md

@@ -3,9 +3,11 @@ name: Logo
 import: "@gradeui/ui"
 subcomponents: []
 props:
-  - sources: LogoSources (required) — artwork keyed by lockup then appearance:
+  - sources?: LogoSources — artwork keyed by lockup then appearance:
       { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }.
-      Each slot is any node (inline <svg>, <img>, component).
+      Each slot is any node (inline <svg>, <img>, component). Omit entirely
+      and a neutral "Logo" placeholder renders (use this in prototypes
+      before real artwork exists).
   - lockup?: "square" | "horizontal" | "icon" (default "horizontal")
   - mode?: "light" | "dark" (default "light") — the background the logo sits on
   - mono?: boolean (default false) — use the single-colour artwork (inherits currentColor)

package/components/ui/screen-animator.md

@@ -0,0 +1,54 @@
+---
+name: ScreenAnimator
+import: "@gradeui/ui"
+subcomponents: []
+props:
+  - shots?: Array<{ zoom?, cx?, cy?, hold?, trans?, label? }> — the tour. Each
+      shot is a zoom (1 = fit, >1 push in), focal point cx/cy (0..1 fractions of
+      the content), hold (ms dwell), trans (ms glide-in), and a caption label.
+      Omit for a static framed view.
+  - autoplay?: boolean (default true)
+  - loop?: boolean (default true) — fly in → shots → back to start → exit → repeat
+  - controls?: boolean (default true) — play / pause / restart transport
+  - spotlight?: boolean (default false) — opt in to dim the edges (vignette) when pushed in
+  - cursor?: boolean (default true) — synthetic cursor pulse on detail shots
+  - enter?: boolean (default true) — fly in from offscreen on start
+  - stage?: string — CSS background of the stage behind the screen (default dark)
+  - backdrop?: React.ReactNode — a live layer behind the content (image, gradient, or a <ThreeScene> shader)
+  - className?: string
+  - children: React.ReactNode (the screen to animate)
+when_to_use: Wrap ANY screen or section in a directed camera — a "live demo
+  director". Give it a list of shots and it tours them (zoom + pan) over the
+  live, still-interactive content, with a focus spotlight, captions, a synthetic
+  cursor, and play/pause. Use it to turn a built screen into an auto-playing
+  product demo (embed it, or drop it on a marketing page). It's the live,
+  editable, re-renderable answer to a screen-recording video.
+composes_with: [AppShell, ThreeScene, Card, Grid, the whole component set (it wraps a screen)]
+aliases: [screen animator, camera, camera tour, director, demo, product demo, zoom pan, spotlight, ken burns, presenter]
+---
+
+```jsx
+// Wrap a live screen; the camera tours the shots and loops.
+<ScreenAnimator
+  shots={[
+    { zoom: 1, cx: 0.5, cy: 0.5, hold: 2400, label: "Overview" },
+    { zoom: 2.4, cx: 0.2, cy: 0.34, hold: 2600, label: "Revenue up 24%" },
+    { zoom: 1.8, cx: 0.5, cy: 0.6, hold: 2800, label: "Pipeline" },
+  ]}
+  backdrop={<ThreeScene preset="aurora" />}
+>
+  <Dashboard />
+</ScreenAnimator>
+```
+
+### Anti-patterns
+
+DO NOT use it as a layout wrapper — it positions `absolute inset-0` and takes
+over the frame. It's for a whole screen/section you want to direct, not a div.
+
+DO NOT hand-tune `trans`/`hold` per shot unless you need to — the defaults
+(soft settle on overview, snappier push on detail) read well. `cx`/`cy` are the
+knobs that matter; they're fractions of the screen (0 = left/top, 0.5 = centre).
+
+DO NOT worry about reduced motion — it settles on the starter frame and stops
+moving automatically under `prefers-reduced-motion`.