@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-composition/references/text.md

@@ -0,0 +1,627 @@
+---
+title: Text Element
+description: Animated text element with automatic character, word, and line splitting for per-unit CSS animation and stagger effects.
+type: reference
+nav:
+  parent: "Media"
+  priority: 20
+  related: ["captions"]
+api:
+  attributes:
+    - name: split
+      type: string
+      default: "word"
+      description: Split mode
+      values: ["line", "word", "char"]
+    - name: stagger
+      type: timestring
+      description: Delay between segments (e.g., "100ms")
+    - name: easing
+      type: string
+      default: "linear"
+      description: Easing function
+    - name: duration
+      type: timestring
+      description: Total duration
+  sub_elements:
+    - tag: ef-text-segment
+      description: Individual segment created when splitting text by word, character, or line
+      attributes:
+        - name: segmentIndex
+          type: number
+          description: Index of this segment in the text
+        - name: segmentText
+          type: string
+          description: Text content of this segment
+        - name: staggerOffsetMs
+          type: number
+          description: Calculated stagger delay for this segment
+        - name: segmentStartMs
+          type: number
+          description: Start time of segment relative to parent
+        - name: segmentEndMs
+          type: number
+          description: End time of segment relative to parent
+        - name: hidden
+          type: boolean
+          description: Whether segment is hidden
+      methods:
+        - name: registerAnimations()
+          signature: "static registerAnimations(id: string, cssText: string): void"
+          description: Register animation styles globally for all text segments
+        - name: unregisterAnimations()
+          signature: "static unregisterAnimations(id: string): void"
+          description: Unregister previously registered animation styles
+      css_variables:
+        - name: --ef-index
+          type: number
+          description: Segment index (0, 1, 2, ...)
+        - name: --ef-stagger-offset
+          type: time
+          description: Calculated stagger delay (e.g., "0ms", "100ms")
+        - name: --ef-seed
+          type: number
+          description: Deterministic random (0-1) based on index
+react:
+  generate: true
+  componentName: Text
+  importPath: "@editframe/react"
+  additionalProps:
+    - name: className
+      type: string
+      description: CSS classes for styling
+    - name: children
+      type: React.ReactNode
+      description: Text content or TextSegment components
+  nav:
+    parent: "Components / Text & Graphics"
+    priority: 30
+    related: ["captions"]
+---
+
+<!-- html-only -->
+# ef-text
+<!-- /html-only -->
+<!-- react-only -->
+# Text
+<!-- /react-only -->
+
+Animated text with character/word/line splitting.
+
+<!-- react-only -->
+## Import
+
+```tsx
+import { Text, TextSegment } from "@editframe/react";
+```
+<!-- /react-only -->
+
+## Basic Usage
+
+<!-- html-only -->
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text duration="5s" class="text-white text-2xl">Static text</ef-text>
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+<Text duration="5s" className="text-white text-4xl">
+  Hello World
+</Text>
+```
+<!-- /react-only -->
+
+<!-- react-only -->
+## Styled Text
+
+```tsx
+<Text
+  duration="3s"
+  className="text-white text-6xl font-bold text-center"
+>
+  Welcome to Editframe
+</Text>
+```
+
+## Positioned Text
+
+```tsx
+<Timegroup mode="fixed" duration="5s" className="absolute w-full h-full">
+  <Text
+    duration="5s"
+    className="absolute top-8 left-8 text-white text-3xl"
+  >
+    Top Left
+  </Text>
+
+  <Text
+    duration="5s"
+    className="absolute bottom-8 right-8 text-white text-2xl"
+  >
+    Bottom Right
+  </Text>
+</Timegroup>
+```
+<!-- /react-only -->
+
+## Word Split with Stagger
+
+<!-- html-only -->
+Use `split="word"` to animate each word independently with stagger delays.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text split="word" stagger="100ms" duration="4s" class="text-white text-3xl">
+    <template>
+      <ef-text-segment class="fade-in"></ef-text-segment>
+    </template>
+    Each word appears with timing
+  </ef-text>
+
+  <style>
+    @keyframes fadeIn {
+      from { opacity: 0; transform: translateY(20px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+
+    .fade-in {
+      animation: fadeIn 0.5s ease-out;
+      animation-delay: var(--ef-stagger-offset);
+    }
+  </style>
+</ef-timegroup>
+```
+<!-- /html-only -->
+<!-- react-only -->
+Control individual words with `TextSegment`:
+
+```tsx
+<Text duration="3s" className="text-white text-4xl">
+  <TextSegment className="text-red-500">Red</TextSegment>
+  {" "}
+  <TextSegment className="text-blue-500">Blue</TextSegment>
+  {" "}
+  <TextSegment className="text-green-500">Green</TextSegment>
+</Text>
+```
+<!-- /react-only -->
+
+## Character-by-Character Animation
+
+<!-- html-only -->
+Use `split="char"` for character-level effects.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text split="char" stagger="30ms" duration="3s" class="text-yellow-400 text-5xl font-bold">
+    <template>
+      <ef-text-segment class="char-slide"></ef-text-segment>
+    </template>
+    HEADLINES
+  </ef-text>
+
+  <style>
+    @keyframes charSlide {
+      from { opacity: 0; transform: translateX(-20px) rotate(-5deg); }
+      to { opacity: 1; transform: translateX(0) rotate(0); }
+    }
+
+    .char-slide {
+      animation: charSlide 0.3s ease-out;
+      animation-delay: var(--ef-stagger-offset);
+    }
+  </style>
+</ef-timegroup>
+```
+<!-- /html-only -->
+
+## Line-by-Line Reveal
+
+<!-- html-only -->
+Use `split="line"` for line-based animations.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text split="line" stagger="800ms" duration="5s" class="text-white text-2xl text-center">
+    <template>
+      <ef-text-segment class="line-reveal"></ef-text-segment>
+    </template>
+    First line appears
+    Then the second line
+    Finally the third line
+  </ef-text>
+
+  <style>
+    @keyframes lineReveal {
+      from { opacity: 0; transform: translateX(-40px); }
+      to { opacity: 1; transform: translateX(0); }
+    }
+
+    .line-reveal {
+      animation: lineReveal 0.6s ease-out;
+      animation-delay: var(--ef-stagger-offset);
+      display: block;
+    }
+  </style>
+</ef-timegroup>
+```
+<!-- /html-only -->
+
+<!-- html-only -->
+## Custom Animations with registerAnimations()
+
+Use `registerAnimations()` to define reusable animation styles globally.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text split="word" stagger="80ms" duration="4s" class="text-cyan-400 text-4xl font-bold">
+    <template>
+      <ef-text-segment class="bounce-in"></ef-text-segment>
+    </template>
+    BOUNCE EFFECT
+  </ef-text>
+
+  <script>
+    customElements.whenDefined('ef-text-segment').then(() => {
+      const EFTextSegment = customElements.get('ef-text-segment');
+      EFTextSegment.registerAnimations('bounce-demo', `
+        @keyframes bounceIn {
+          0% { transform: scale(0) rotate(-180deg); opacity: 0; }
+          50% { transform: scale(1.3) rotate(0deg); }
+          100% { transform: scale(1) rotate(0deg); opacity: 1; }
+        }
+
+        .bounce-in {
+          animation: bounceIn 0.6s cubic-bezier(0.68, -0.55, 0.265, 1.55);
+          animation-delay: var(--ef-stagger-offset);
+        }
+      `);
+    });
+  </script>
+</ef-timegroup>
+```
+
+## Easing Options
+
+Different easing functions create different animation feels.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex flex-col items-center justify-center gap-8">
+  <!-- Linear easing -->
+  <ef-text split="word" stagger="60ms" easing="linear" duration="3s" class="text-white text-xl">
+    <template>
+      <ef-text-segment class="scale-in"></ef-text-segment>
+    </template>
+    Linear easing (constant speed)
+  </ef-text>
+
+  <!-- Ease-out easing -->
+  <ef-text split="word" stagger="60ms" easing="ease-out" duration="3s" class="text-green-400 text-xl">
+    <template>
+      <ef-text-segment class="scale-in"></ef-text-segment>
+    </template>
+    Ease-out (starts fast ends slow)
+  </ef-text>
+
+  <!-- Cubic-bezier easing -->
+  <ef-text split="word" stagger="60ms" duration="3s" class="text-blue-400 text-xl">
+    <template>
+      <ef-text-segment class="scale-bounce"></ef-text-segment>
+    </template>
+    Custom cubic-bezier (bouncy)
+  </ef-text>
+
+  <style>
+    @keyframes scaleIn {
+      from { opacity: 0; transform: scale(0); }
+      to { opacity: 1; transform: scale(1); }
+    }
+
+    .scale-in {
+      animation: scaleIn 0.4s;
+      animation-delay: var(--ef-stagger-offset);
+    }
+
+    .scale-bounce {
+      animation: scaleIn 0.5s cubic-bezier(0.68, -0.55, 0.265, 1.55);
+      animation-delay: var(--ef-stagger-offset);
+    }
+  </style>
+</ef-timegroup>
+```
+
+## StaggerMs Timing Variations
+
+Control the delay between segments to create different rhythms.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex flex-col items-center justify-center gap-10">
+  <!-- Fast stagger -->
+  <ef-text split="word" stagger="40ms" duration="3s" class="text-white text-2xl">
+    <template>
+      <ef-text-segment class="pop-in"></ef-text-segment>
+    </template>
+    Fast stagger feels energetic
+  </ef-text>
+
+  <!-- Medium stagger -->
+  <ef-text split="word" stagger="120ms" duration="4s" class="text-yellow-400 text-2xl">
+    <template>
+      <ef-text-segment class="pop-in"></ef-text-segment>
+    </template>
+    Medium stagger is balanced
+  </ef-text>
+
+  <!-- Slow stagger -->
+  <ef-text split="word" stagger="250ms" duration="5s" class="text-pink-400 text-2xl">
+    <template>
+      <ef-text-segment class="pop-in"></ef-text-segment>
+    </template>
+    Slow stagger adds drama
+  </ef-text>
+
+  <style>
+    @keyframes popIn {
+      from { opacity: 0; transform: scale(0.5) translateY(10px); }
+      to { opacity: 1; transform: scale(1) translateY(0); }
+    }
+
+    .pop-in {
+      animation: popIn 0.4s ease-out;
+      animation-delay: var(--ef-stagger-offset);
+    }
+  </style>
+</ef-timegroup>
+```
+
+## Using --ef-seed for Random Variation
+
+The `--ef-seed` CSS variable provides deterministic randomness per segment.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text split="word" stagger="100ms" duration="4s" class="text-white text-3xl">
+    <template>
+      <ef-text-segment class="random-slide"></ef-text-segment>
+    </template>
+    Words slide from random angles
+  </ef-text>
+
+  <style>
+    @keyframes randomSlide {
+      from {
+        opacity: 0;
+        transform:
+          translateX(calc(var(--ef-seed) * 80px - 40px))
+          translateY(calc(var(--ef-seed) * 60px - 30px))
+          rotate(calc(var(--ef-seed) * 60deg - 30deg));
+      }
+      to {
+        opacity: 1;
+        transform: translateX(0) translateY(0) rotate(0);
+      }
+    }
+
+    .random-slide {
+      animation: randomSlide 0.6s cubic-bezier(0.34, 1.56, 0.64, 1);
+      animation-delay: var(--ef-stagger-offset);
+    }
+  </style>
+</ef-timegroup>
+```
+
+## Lower Third
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black relative">
+  <ef-text duration="4s" class="absolute bottom-16 left-4 bg-blue-600/90 text-white px-4 py-2 rounded-md text-sm font-semibold">
+    Scene Label
+  </ef-text>
+</ef-timegroup>
+```
+
+## Multiple Segments Per Word
+
+Create multiple segments for each text unit by using multiple `ef-text-segment` elements in the template.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black flex items-center justify-center">
+  <ef-text split="word" stagger="120ms" duration="4s" class="text-white text-3xl">
+    <template>
+      <!-- Shadow segment behind -->
+      <ef-text-segment class="segment-shadow"></ef-text-segment>
+      <!-- Main segment on top -->
+      <ef-text-segment class="segment-main"></ef-text-segment>
+    </template>
+    Layered shadow effect
+  </ef-text>
+
+  <style>
+    .segment-shadow {
+      position: absolute;
+      color: #3b82f6;
+      filter: blur(4px);
+      animation: shadowSlide 0.6s ease-out;
+      animation-delay: var(--ef-stagger-offset);
+    }
+
+    .segment-main {
+      position: relative;
+      animation: mainSlide 0.6s ease-out;
+      animation-delay: var(--ef-stagger-offset);
+    }
+
+    @keyframes shadowSlide {
+      from { opacity: 0; transform: translate(-20px, 10px); }
+      to { opacity: 0.6; transform: translate(4px, 4px); }
+    }
+
+    @keyframes mainSlide {
+      from { opacity: 0; transform: translate(-20px, 0); }
+      to { opacity: 1; transform: translate(0, 0); }
+    }
+  </style>
+</ef-timegroup>
+```
+
+## Unregistering Animations
+
+Remove previously registered animations when no longer needed.
+
+```javascript
+const EFTextSegment = customElements.get('ef-text-segment');
+EFTextSegment.unregisterAnimations('bounce');
+```
+
+## ef-text-segment Reference
+
+`ef-text-segment` elements are automatically created by `ef-text` when using split modes. Each segment represents a word, character, or line and can be styled and animated independently.
+
+### CSS Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `--ef-index` | number | Segment index (0, 1, 2, ...) |
+| `--ef-stagger-offset` | time | Calculated stagger delay (e.g., "0ms", "100ms") |
+| `--ef-seed` | number | Deterministic random (0-1) based on index |
+
+### Technical Notes
+
+- Segments are automatically created by `ef-text` when using split modes
+- Segments inherit animation properties from parent `ef-text` element
+- `registerAnimations()` uses adopted stylesheets for efficient global sharing
+- Non-whitespace segments automatically become `inline-block` when animated to enable transforms
+- Whitespace segments remain `inline` to preserve text flow
+<!-- /html-only -->
+
+<!-- react-only -->
+## Dynamic Text
+
+```tsx
+interface TitleData {
+  text: string;
+  duration: string;
+  className: string;
+}
+
+const titles: TitleData[] = [
+  { text: "Scene 1", duration: "3s", className: "text-red-500" },
+  { text: "Scene 2", duration: "3s", className: "text-blue-500" },
+  { text: "Scene 3", duration: "3s", className: "text-green-500" },
+];
+
+<Timegroup mode="sequence" className="w-[800px] h-[500px]">
+  {titles.map((title, i) => (
+    <Timegroup key={i} mode="fixed" duration={title.duration} className="absolute w-full h-full flex items-center justify-center">
+      <Text duration={title.duration} className={`text-4xl ${title.className}`}>
+        {title.text}
+      </Text>
+    </Timegroup>
+  ))}
+</Timegroup>
+```
+
+## Text with Background
+
+```tsx
+<Text
+  duration="5s"
+  className="bg-black/50 text-white text-3xl px-4 py-2 rounded"
+>
+  Overlay Text
+</Text>
+```
+
+## Multi-line Text
+
+```tsx
+<Text
+  duration="5s"
+  className="text-white text-2xl text-center max-w-[600px]"
+>
+  This is a longer text that will wrap across multiple lines
+  when it reaches the maximum width.
+</Text>
+```
+
+## Animated Text with useTimingInfo
+
+```tsx
+import { Text } from "@editframe/react";
+import { useTimingInfo } from "@editframe/react";
+
+const FadingText = ({ children }: { children: React.ReactNode }) => {
+  const { ref, percentComplete } = useTimingInfo();
+
+  return (
+    <Text
+      ref={ref}
+      duration="5s"
+      className="text-white text-4xl"
+      style={{ opacity: percentComplete }}
+    >
+      {children}
+    </Text>
+  );
+};
+```
+
+## Register Custom Animations
+
+Use `TextSegment.registerAnimations()` to define animations shared across all segments:
+
+```tsx
+import { TextSegment } from "@editframe/react";
+
+TextSegment.registerAnimations("customAnimations", `
+  @keyframes slideIn {
+    from { transform: translateX(-100%); opacity: 0; }
+    to { transform: translateX(0); opacity: 1; }
+  }
+  .slide-in { animation: slideIn 0.5s ease-out; }
+`);
+
+const AnimatedText = () => (
+  <Text duration="5s" className="text-white text-4xl">
+    <TextSegment className="slide-in inline-block">Slides</TextSegment>
+    {" "}
+    <TextSegment className="bounce-in inline-block">Bounces</TextSegment>
+  </Text>
+);
+```
+
+Unregister animations when no longer needed:
+
+```tsx
+import { useEffect } from "react";
+import { TextSegment } from "@editframe/react";
+
+const MyComponent = () => {
+  useEffect(() => {
+    TextSegment.registerAnimations("myAnimations", `/* styles */`);
+    return () => {
+      TextSegment.unregisterAnimations("myAnimations");
+    };
+  }, []);
+
+  return (/* ... */);
+};
+```
+
+## TextSegment Reference
+
+Each TextSegment has access to CSS variables for advanced animations:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `--ef-index` | number | Segment index (0, 1, 2, ...) |
+| `--ef-stagger-offset` | time | Calculated stagger delay |
+| `--ef-seed` | number | Deterministic random (0-1) based on index |
+
+- TextSegment requires a parent `Text` component
+- Use `inline-block` display for transform animations to work correctly
+- Animation styles are shared globally across all TextSegment instances
+- Each segment's `--ef-seed` value is deterministic based on its index
+<!-- /react-only -->